Repository navigation
REST API Reference #8119
Description
Description
We need documentation to be available in a user-friendly form. The YAML file does not belong to this format. We can use swagger UI or something similar
More information about the docs for REST API is available:
Docs for REST API
Use case / motivation
Users expect the specification to be in an accessible form.
Related Issues
N/A
Reacted by Adam Dobrawy
Activity
sarahmaas commentedon May 22, 2020
I'd like to work on adding swagger UI for this.
mik-laj commentedon Jun 25, 2020
@sarahmaas I missed your comment. Could you prepare POC to show what it could look like? I wonder if we should integrate Swagger UI with Sphinx or leave it independent.
mik-laj commentedon Jun 25, 2020
We are currently publishing documentation in two places:
Does anyone have any opinions about other tools? I have heard positive reviews about Redoc. What could the integration of Sphinx with Redoc look like? I have the idea that when publishing documentation on airflow.apache.org we can copy HTML files from redoc-cli to the _build directory. For publication on airflow.readthedocs.org, we can replace use other service to render docs.
Here is a preview of these two tools.
Swaagger UI:
https://editor.swagger.io/?url=https://raw.githubusercontent.com/apache/airflow/master/airflow/api_connexion/openapi/v1.yaml
Redoc:
https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/apache/airflow/master/airflow/api_connexion/openapi/v1.yaml
TODO Tasks:
potiuk commentedon Jun 25, 2020
Redoc seems much more user-friendly for me. But I have not much experience with using it. Swagger is fairly "standard" on one hand, but also it is a bit "dated" in terms of UI/UX/friendliness.
mik-laj commentedon Jun 25, 2020
I will add that in the "Docs" tab from the Web UI there is also reference documentation available (Swagger UI and Redoc), but we need access to the documentation without a Web server. We can support two technologies also in the generated documentation, if this is not a big problem. It depends on the integration method chosen.
sarahmaas commentedon Jun 29, 2020
I'm afraid I don't have as much time to help out with this now as I did when I volunteered to take it on 😞