apache/airflow

AIP-84 Sync documentation and permissions

Open

#43,430 opened on Oct 28, 2024

View on GitHub
 (13 comments) (4 reactions) (0 assignees)Python (16,781 forks)batch import
area:APIgood first issuekind:documentationkind:feature

Repository metrics

Stars
 (44,809 stars)
PR merge metrics
 (Avg merge 6d 22h) (844 merged PRs in 30d)

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

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.
Tech stack
pythonfastapi
Domain
apidocumentationauthorization
Issue type
Feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
4
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
Over 1 week
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Blocked
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Mostly clear
Prerequisites
Authentication and permissions implemented (issue #42360)Familiarity with FastAPI and Airflow APIExperience with documentation generation tools
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
15