REST API Reference

[mik-laj]

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

[sarahmaas]

I'd like to work on adding swagger UI for this.

[mik-laj]

@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]

We are currently publishing documentation in two places:

• for master: https://airflow.readthedocs.io/en/latest/
• for released version: https://airflow.apache.org/docs/ (repo: https://github.com/apache/airflow-site, information on the publication process is in the guide: https://github.com/apache/airflow-site/blob/master/CONTRIBUTE.md )

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:

• Choose a documentation builder
• Integrate with airflow.apache.org
• Integrate with readthedocs.io
• Tests
• Documentation

[potiuk]

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]

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]

@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.

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 😞