Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Enhance API documentation and examples #219

Open
kshitijrajsharma opened this issue Mar 3, 2024 · 47 comments · May be fixed by nwekealex65/raw-data-api#1, tony-nyagah/raw-data-api#3, #232, mvhammedali/raw-data-api#1 or #231
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers outreachy

Comments

@kshitijrajsharma
Copy link
Member

kshitijrajsharma commented Mar 3, 2024

This issue aims to refine our API documentation to the point where it is considered exemplary in terms of compliance, clarity, and completeness. The task involves reviewing, updating, and testing our documentation against the OpenAPI specification and then submitting it to Rate My OpenAPI to match our adherence level.

Objectives

  • Ensure OpenAPI Compliance: Achieve full compliance with the OpenAPI specification for our API documentation.
  • Enhance Documentation Quality: Provide clear, comprehensive examples for each endpoint, covering request and response schemas, parameters, and error codes.
  • Achieve High Rating: Aim for a high rating on "Rate My OpenAPI", which will serve as a testament to the quality and compliance of our API documentation.
  • Tool Compatibility: Ensure the documentation facilitates automatic generation of client libraries, SDKs, and interface definitions, proving its utility across various platforms including Swagger UI and Postman.

Requirements

  • Understanding of the OpenAPI specification.
  • Proficiency in FastAPI and its automatic documentation features.
  • Familiarity with documentation generation and validation tools.

Getting Started

  • Initial Review and Assessment: Start by evaluating our current API documentation against the OpenAPI standard. Identify areas for improvement and document your findings.

  • Familiarize with Validation Criteria: Understand the openapi validations and docstring methods. This insight will guide the enhancement process.

  • Update and Refine Documentation: Implement necessary changes to the API documentation, ensuring it is comprehensive, clear, and fully compliant with the OpenAPI specification. Incorporate detailed examples for better understanding and usability.

  • Validation and Testing: Use tools from OpenAPI Tools and the Swagger Editor for validating the updated documentation. Ensure it is error-free and meets the expected standards.

  • Submit to Rate My OpenAPI: Once the documentation is polished and validated, submit it to Rate My OpenAPI for rating. Analyze the feedback and make any required adjustments.

Resources

What should be included in PR:

  • Black formatter should be used
  • At least mention following section

--- What does this PR do ?

  • Detail summary about the changes you have done, Mention link of issue you have worked on

--- Consideration:

  • What are the steps/alternatives you have considered while developing

--- How to test ?

  • Steps to tests

Support:

Feel free to ask questions or seek clarifications by commenting on this issue. We're excited to see your contributions.

How to Proceed:

  • Fork the repository and set up the project locally.
  • Comment on this issue mentioning you will be contributing
  • Familiarize yourself with the codebase and FastAPI framework & Review endpoints
  • Start by creating new branch in your fork with functional branch name like enhance/user-auth-api
  • Write API documentation doc strings / examples , fix related issues and submit them as a pull request in your own fork
  • Download your local version of openapi form and submit here or use any other openapi tools for coverage and validation
  • Come back to this issue thread and drop your pull request URL for initial feedback.
  • Gradually work on covering more components and functionalities. Once approved, you can raise PR to this main repo
@kshitijrajsharma kshitijrajsharma added documentation Improvements or additions to documentation good first issue Good for newcomers outreachy labels Mar 3, 2024
@ohthebrave
Copy link

kindly assign this issue to me

@damidfkm
Copy link

damidfkm commented Mar 4, 2024

i will be working on this issue

@kshitijrajsharma
Copy link
Member Author

Sure go ahead . This issue can be worked on by multiple people. Feel free to drop your questions if you have any .

@Payne680
Copy link

Payne680 commented Mar 5, 2024

I will be working on this issue

@hamzambo
Copy link

hamzambo commented Mar 5, 2024

I will be working on this issue. Would like to know if the project can be run on windows.

@owolabioromidayo
Copy link

Hello! I will also be working on this.

@nifedara
Copy link

nifedara commented Mar 5, 2024

I will be working on this issue. Would like to know if the project can be run on windows.

Yes, it can.
But you have to set the project up using Docker.
Check the project's ReadMe for more details.

@owolabioromidayo
Copy link

Hi! I made a PR with some changes to the openapi.json file. Do I also have to ensure that FastAPI generates those same changes?

@kshitijrajsharma
Copy link
Member Author

kshitijrajsharma commented Mar 5, 2024

Hi! I made a PR with some changes to the openapi.json file. Do I also have to ensure that FastAPI generates those same changes?

@owolabioromidayo
Yes , It should be dynamic from the application . Its a good practice to score it using openapi tools

@owolabioromidayo
Copy link

Okay, thank you. I will work on that now.

@hamzambo
Copy link

hamzambo commented Mar 5, 2024

I will be working on this issue. Would like to know if the project can be run on windows.

Yes, it can. But you have to set the project up using Docker. Check the project's ReadMe for more details.

Thanks. Will do that.

@ayushisinxx
Copy link

I am willing to work on this issue.

@Elsie-ND
Copy link

Elsie-ND commented Mar 6, 2024

Please I will be working on this issue.

@KafayatYusuf
Copy link

Interested in working on this issue

@Talikamuhib
Copy link

excited for it! 👍

@nifedara
Copy link

nifedara commented Mar 7, 2024

I will be contributing

@donaldte
Copy link

donaldte commented Mar 7, 2024

Hello @kshitijrajsharma, my name is Donald Tedom I'm outreachy applicant, i will be contributing in this project.

@DhwaniSaliya
Copy link

Willing to contribute to this project by working on this issue.

@maureenblack
Copy link

Hi, I will be contributing on this issue.

@tony-nyagah
Copy link

Hello. I will be contributing to this issue.

@nifedara
Copy link

nifedara commented Mar 12, 2024

Hello @kshitijrajsharma,
Here is my PR

I would appreciate your feedback as I go on to cover enhancing the documentation for more components

@mmbogajemimah
Copy link

mmbogajemimah commented Mar 12, 2024

Hi.
I am Jemimah Mmboga
I will be contributing to this issue.

@Arnav2824
Copy link

Hi.
I will be contributing to this issue.

@nwekealex65
Copy link

Hello @kshitijrajsharma I will be working on this issue

@mmbogajemimah
Copy link

Hi @kshitijrajsharma I am working on this Issue

@nwekealex65
Copy link

@kshitijrajsharma please review my PR nwekealex65#4

This was referenced Mar 22, 2024
@KafayatYusuf
Copy link

KafayatYusuf commented Mar 22, 2024

Hi @kshitijrajsharma. Kindly review my PR and assist with a feedback.

@tony-nyagah tony-nyagah linked a pull request Mar 24, 2024 that will close this issue
7 tasks
@tony-nyagah
Copy link

Hello @kshitijrajsharma. Here is my PR: tony-nyagah#3
I would greatly appreciate feedback on this. Thank you for your time.

@mvhammedali
Copy link

Here is my PR mvhammedali#1 :D

@nwekealex65
Copy link

Hello @kshitijrajsharma here is my PR nwekealex65#5 please I would love a review

@nwekealex65
Copy link

Good day @kshitijrajsharma please could you help review my PR nwekealex65#6

@mmbogajemimah mmbogajemimah linked a pull request Mar 26, 2024 that will close this issue
5 tasks
@medinasheriff
Copy link

Hello, I will be contributing to this issue.

@durotimmi-sk
Copy link

hi, i'll like to work on this issue

@medinasheriff medinasheriff linked a pull request Apr 2, 2024 that will close this issue
7 tasks
@medinasheriff
Copy link

Hello @kshitijrajsharma @owolabioromidayo Kindly review my PR #244

@nifedara
Copy link

nifedara commented Apr 2, 2024

Hello @kshitijrajsharma

Here is another PR:

Oluwanifemi Daramola Raw Data Api 2

It's similar to the PR I dropped initially(above), but I had created one branch for all the changes I made to the raw-data-api documentation while in this, I created a separate branch for each endpoint change I make.

I just realized that that was what your instruction suggested to do. e.g enhance/auth-api and so on

@KafayatYusuf
Copy link

I split this larger PR which might be difficult to review into smaller PRs by endpoints to improve clarity, faster review and integration.

auth
extract
tasks
stats
other
custom_exports

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment