AIP-84 Sync documentation and permissions · apache/airflow#43430

(13 comments) (4 reactions) (0 assignees)Python (44,809 stars) (16,781 forks)batch import

area:APIgood first issuekind:documentationkind:feature

Description

More context here https://github.com/apache/airflow/issues/43140#issuecomment-2431304177

To avoid additional mismatch between the code and the documentation, we could add a small layer to automatically detect and document the API permissions for each route. Ideally the swagger and maybe also this documentation page should be automatically populated from the FastAPI code.

Note: To be able to work on this, authentication and permissions need to be implemented first.

Committer

I acknowledge that I am a maintainer/committer of the Apache Airflow project.

Contributor guide

Tech stack: pythonfastapi
Domain: apidocumentationauthorization
Issue type: feature
Difficulty: 4
Estimated time: over 1 week
Activity status: blocked
Clarity: mostly clear
Prerequisites: Authentication and permissions implemented (issue #42360)Familiarity with FastAPI and Airflow APIExperience with documentation generation tools
Newbie friendliness: 15
Research direction: First, review the current API documentation generation in Airflow, particularly the FastAPI application setup in airflow/auth/manager/fastapi.py and the OpenAPI schema generation. Then, study the proposed authentication and permissions implementation in issue #42360 to understand the expected permission structure. After that, design a mechanism to automatically annotate each route with required permissions and integrate it into the existing documentation generation process, ensuring it populates both the Swagger UI and the DAG level permissions documentation page.