raw-data-api
raw-data-api copied to clipboard
hotosm
Enhance API documentation and examples
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
- FastAPI Documentation
- OpenAPI Specification
- OpenAPI Tools
- Rate My OpenAPI
- Find begineer guide to contribute to HOTOSM Tools here
- Find HOTOSM Developer guidelines here
- Current API documentation
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
Sure go ahead . This issue can be worked on by multiple people. Feel free to drop your questions if you have any .
I will be working on this issue. Would like to know if the project can be run on windows.
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.
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?
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
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.
Hello @kshitijrajsharma, my name is Donald Tedom I'm outreachy applicant, i will be contributing in this project.
Hello @kshitijrajsharma, Here is my PR
I would appreciate your feedback as I go on to cover enhancing the documentation for more components
Hi @kshitijrajsharma. Submitted my pull request for your feedback to enable me proceed. https://github.com/hotosm/raw-data-api/pull/227
Here are my PRs @kshitijrajsharma. Link: https://github.com/tony-nyagah/raw-data-api/pull/1 and https://github.com/tony-nyagah/raw-data-api/pull/2 I would greatly appreciate feedback on this. Thank you for your time.