[Feature request]: Add OpenAPI/Swagger Documentation for the REST API

[Guts]

Description

I would like to request the addition of OpenAPI (Swagger) documentation for the REST API of the QGIS web application. This would greatly enhance the usability of the API by providing clear and interactive documentation for developers who are integrating or consuming the API.

Why is this needed?

• Improved Developer Experience: OpenAPI/Swagger docs offer a clear and interactive way for developers to explore and understand the API endpoints, request formats, and expected responses. This reduces the barrier for new users to consume the API.
• Standardization: OpenAPI is a widely adopted standard for API documentation, making it easier for developers to interact with and understand the QGIS-Django API.
• Ease of Integration: Swagger-generated docs also allow for testing API requests directly from the documentation, which can simplify integration and troubleshooting.

Proposed Solution

1. Generate OpenAPI Specification: Use tools like Django REST framework's built-in support for generating OpenAPI specs.
2. Swagger UI Integration: Host the Swagger UI within the project or as part of the API endpoint, allowing developers to visualize and interact with the API.
3. Automation: Ensure that the OpenAPI schema is updated automatically with any changes to the API endpoints, possibly via CI/CD pipelines.

Additional Context

• Django REST framework provides an integrated solution for generating OpenAPI 3.0 specifications. Here's the official guide on OpenAPI schema generation.
• Implementing Swagger would help align with the broader developer ecosystem and improve API consumption, making the QGIS project more accessible to a wider audience.

---

Additional Information

Any relevant links or references can be included here, such as:

• OpenAPI Specification
• Swagger UI
• Django REST Framework OpenAPI Schema

[Xpirix]

Hi @Guts

Thank you so much for this suggestion. I indeed agree with your idea of implementing proper REST API docs.

After investigating the code, I noticed that only the resources hub has a proper REST API using the Django REST Framework. Their swagger documentation is available at https://plugins.qgis.org/swagger/ and the redoc is at https://plugins.qgis.org/redoc/.

However, implementing a proper REST API for other views would require new views and URLs (along with serializers) before we can add them to the documentation, as they are mostly based on Django generic views. The token-based plugin upload feature implemented with qgis/QGIS-Django#326, for example, uses the same view but with the possibility of using a token rather than a password authentication when a developer wants to upload a new version from the CI.

I'm eager to implement Rest APIs, but I think we should define the approach/plan first because implementing a complete API for the entire plugins app will involve significant changes. For example, prioritising the plugin uploads feature (new version, new plugins...).

Regards,