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