Enhance API documentation and examples

[kshitijrajsharma]

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

[ohthebrave]

kindly assign this issue to me

[damidfkm]

i will be working on this issue

[kshitijrajsharma]

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

[Payne680]

I will be working on this issue

[hamzambo]

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

[owolabioromidayo]

Hello! I will also be working on this.

[nifedara]

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]

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]

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]

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

[hamzambo]

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]

I am willing to work on this issue.

[Elsie-ND]

Please I will be working on this issue.

[KafayatYusuf]

Interested in working on this issue

[Talikamuhib]

excited for it! 👍

[nifedara]

I will be contributing

[donaldte]

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

[DhwaniSaliya]

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

[maureenblack]

Hi, I will be contributing on this issue.

[tony-nyagah]

Hello. I will be contributing to this issue.

[nifedara]

Hello @kshitijrajsharma,
Here is my PR

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

[mmbogajemimah]

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

[Arnav2824]

Hi.
I will be contributing to this issue.

[nwekealex65]

Hello @kshitijrajsharma I will be working on this issue

[mmbogajemimah]

Hi @kshitijrajsharma I am working on this Issue

[nwekealex65]

@kshitijrajsharma please review my PR nwekealex65#4

[KafayatYusuf]

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

[tony-nyagah]

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

[mvhammedali]

Here is my PR mvhammedali#1 :D

[nwekealex65]

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

[nwekealex65]

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

[medinasheriff]

Hello, I will be contributing to this issue.

[durotimmi-sk]

hi, i'll like to work on this issue

[medinasheriff]

Hello @kshitijrajsharma @owolabioromidayo Kindly review my PR #244

[nifedara]

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]

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