Skip to content

Commit dc2e21b

Browse files
authored
Replace Sphinx Redoc with Swagger API Docs (#67390)
* Replace Sphinx Redoc with Swagger API Docs * Upgrade Swagger version * Fix CSS for dark mode * Upgrade swagger-plugin-for-sphinx>=7.1.0 and remove mirror logic * Cleanup
1 parent 4e5cf1b commit dc2e21b

14 files changed

Lines changed: 159 additions & 133 deletions

File tree

‎airflow-core/docs/conf.py‎

Lines changed: 9 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,6 @@
2424
import os
2525
import pathlib
2626
import re
27-
from pathlib import Path
2827
from typing import Any
2928

3029
from docs.utils.conf_constants import (
@@ -37,12 +36,14 @@
3736
AUTOAPI_OPTIONS,
3837
BASIC_AUTOAPI_IGNORE_PATTERNS,
3938
BASIC_SPHINX_EXTENSIONS,
40-
REDOC_SCRIPT_URL,
4139
SMARTQUOTES_EXCLUDES,
4240
SPELLING_WORDLIST_PATH,
4341
SPHINX_DESIGN_STATIC_PATH,
44-
SPHINX_REDOC_EXTENSIONS,
42+
SPHINX_SWAGGER_EXTENSION,
4543
SUPPRESS_WARNINGS,
44+
SWAGGER_BUNDLE_URI,
45+
SWAGGER_CSS_URI,
46+
SWAGGER_PRESENT_URI,
4647
filter_autoapi_ignore_entries,
4748
get_autodoc_mock_imports,
4849
get_configs_and_deprecations,
@@ -58,8 +59,6 @@
5859
from packaging.version import Version, parse as parse_version
5960

6061
import airflow
61-
from airflow.api_fastapi.auth.managers.simple.openapi import __file__ as sam_openapi_file
62-
from airflow.api_fastapi.core_api.openapi import __file__ as main_openapi_file
6362
from airflow.configuration import retrieve_configuration_description
6463

6564
PACKAGE_NAME = "apache-airflow"
@@ -91,11 +90,12 @@
9190
# ones.
9291
extensions = BASIC_SPHINX_EXTENSIONS
9392

94-
# -- Options for sphinxcontrib.redoc -------------------------------------------
95-
# See: https://sphinxcontrib-redoc.readthedocs.io/en/stable/
93+
extensions.append(SPHINX_SWAGGER_EXTENSION)
9694

97-
extensions.extend(SPHINX_REDOC_EXTENSIONS)
98-
redoc_script_url = REDOC_SCRIPT_URL
95+
swagger_present_uri = SWAGGER_PRESENT_URI
96+
swagger_bundle_uri = SWAGGER_BUNDLE_URI
97+
swagger_css_uri = SWAGGER_CSS_URI
98+
swagger_mirror_external_resources = True # Ensure we embed external resources prevent tracking
9999

100100
extensions.extend(
101101
[
@@ -357,27 +357,6 @@ def add_airflow_core_exclude_patterns_to_sphinx(exclude_patterns: list[str]):
357357

358358
graphviz_output_format = "svg"
359359

360-
main_openapi_path = Path(main_openapi_file).parent.joinpath("v2-rest-api-generated.yaml")
361-
sam_openapi_path = Path(sam_openapi_file).parent.joinpath("v2-simple-auth-manager-generated.yaml")
362-
redoc = [
363-
{
364-
"name": "Simple auth manager token API",
365-
"page": "core-concepts/auth-manager/simple/sam-token-api-ref",
366-
"spec": sam_openapi_path.as_posix(),
367-
"opts": {
368-
"hide-hostname": True,
369-
},
370-
},
371-
{
372-
"name": "Airflow REST API",
373-
"page": "stable-rest-api-ref",
374-
"spec": main_openapi_path.as_posix(),
375-
"opts": {
376-
"hide-hostname": True,
377-
},
378-
},
379-
]
380-
381360

382361
def setup(sphinx):
383362
sphinx.connect("autoapi-skip-member", skip_util_classes_extension)

‎airflow-core/docs/core-concepts/auth-manager/simple/sam-token-api-ref.rst‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,5 +19,7 @@
1919
Simple auth manager token API
2020
=============================
2121

22-
It's a stub file. It will be converted automatically during the build process
23-
to the valid documentation by the Sphinx plugin. See: /docs/conf.py
22+
.. swagger-plugin:: ../../../../src/airflow/api_fastapi/auth/managers/simple/openapi/v2-simple-auth-manager-generated.yaml
23+
:id: sam-token-api-ref
24+
:page-title: Simple auth manager token API
25+
:swagger-options: { "tryItOutEnabled": "false", "supportedSubmitMethods": [] }

‎airflow-core/docs/stable-rest-api-ref.rst‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,10 @@
1616
specific language governing permissions and limitations
1717
under the License.
1818
19-
Airflow public API reference
20-
============================
19+
Airflow public REST API reference
20+
=================================
2121

22-
It's a stub file. It will be converted automatically during the build process
23-
to the valid documentation by the Sphinx plugin. See: airflow-core/docs/conf.py
22+
.. swagger-plugin:: ../src/airflow/api_fastapi/core_api/openapi/v2-rest-api-generated.yaml
23+
:id: core-rest-api-ref
24+
:page-title: Airflow public REST API
25+
:swagger-options: { "tryItOutEnabled": "false", "supportedSubmitMethods": [] }

‎airflow-ctl/docs/conf.py‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -33,11 +33,9 @@
3333
AUTOAPI_OPTIONS,
3434
BASIC_AUTOAPI_IGNORE_PATTERNS,
3535
BASIC_SPHINX_EXTENSIONS,
36-
REDOC_SCRIPT_URL,
3736
SMARTQUOTES_EXCLUDES,
3837
SPELLING_WORDLIST_PATH,
3938
SPHINX_DESIGN_STATIC_PATH,
40-
SPHINX_REDOC_EXTENSIONS,
4139
SUPPRESS_WARNINGS,
4240
filter_autoapi_ignore_entries,
4341
get_autodoc_mock_imports,
@@ -88,11 +86,6 @@
8886
# ones.
8987
extensions = BASIC_SPHINX_EXTENSIONS
9088

91-
# -- Options for sphinxcontrib.redoc -------------------------------------------
92-
# See: https://sphinxcontrib-redoc.readthedocs.io/en/stable/
93-
94-
extensions.extend(SPHINX_REDOC_EXTENSIONS)
95-
redoc_script_url = REDOC_SCRIPT_URL
9689

9790
extensions.extend(
9891
[

‎devel-common/pyproject.toml‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -98,12 +98,9 @@ dependencies = [
9898
"sphinxcontrib-jsmath>=1.0.1",
9999
"sphinxcontrib-mermaid>=1.0.0",
100100
"sphinxcontrib-qthelp>=1.0.3",
101-
"sphinxcontrib-redoc>=1.6.0",
102101
"sphinxcontrib-serializinghtml>=1.1.5",
103102
"sphinxcontrib-spelling>=8.0.0",
104-
# setuptools 82.0.0+ causes redoc to fail due to pkg_resources removal
105-
# until https://github.com/sphinx-contrib/redoc/issues/53 is resolved
106-
"setuptools<82.0.0",
103+
"swagger-plugin-for-sphinx>=7.1.0",
107104
]
108105
"docs-gen" = [
109106
"diagrams>=0.24.4",

‎devel-common/sphinx_design/static/custom.css‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,3 +97,53 @@ a.headerlink svg {
9797
margin: -117px 0 0; /* negative fixed header height */
9898
}
9999
}
100+
101+
/*
102+
Some layout optimization especially for dark mode for Swagger API reference
103+
*/
104+
105+
/* Hide the authorize button which is use-less in docs w/o API running behind */
106+
.swagger-ui div.scheme-container {
107+
display: none;
108+
}
109+
110+
/* Set text color to white in dark mode for better readability */
111+
[data-bs-theme="dark"] .swagger-ui .title,
112+
[data-bs-theme="dark"] .swagger-ui h4,
113+
[data-bs-theme="dark"] .swagger-ui .opblock .opblock-section-header h4,
114+
[data-bs-theme="dark"] .swagger-ui .parameter__name,
115+
[data-bs-theme="dark"] .swagger-ui .parameter__type,
116+
[data-bs-theme="dark"] .swagger-ui p {
117+
color: var(--bs-emphasis-color);
118+
}
119+
120+
[data-bs-theme="dark"] .swagger-ui a.nostyle {
121+
color: var(--bs-link-color);
122+
}
123+
124+
[data-bs-theme="dark"] .swagger-ui .opblock .opblock-summary-description {
125+
color: var(--bs-secondary-color);
126+
}
127+
128+
[data-bs-theme="dark"] .swagger-ui svg {
129+
stroke: var(--bs-emphasis-color);
130+
}
131+
132+
[data-bs-theme="dark"] .swagger-ui .opblock .opblock-section-header {
133+
color: var(--bs-emphasis-color);
134+
background-color: var(--bs-secondary-bg);
135+
}
136+
137+
[data-bs-theme="dark"] .swagger-ui input[disabled],
138+
[data-bs-theme="dark"] .swagger-ui select[disabled],
139+
[data-bs-theme="dark"] .swagger-ui select,
140+
[data-bs-theme="dark"] .swagger-ui textarea[disabled] {
141+
border: 1px solid var(--bs-border-color) ;
142+
color: var(--bs-emphasis-color);
143+
background-color: var(--bs-secondary-bg);
144+
}
145+
146+
/* Somehow some dark mode is showing-up also in light mode for code areas, fix it here */
147+
.swagger-ui pre code {
148+
background-color: rgb(51, 51, 51);
149+
}

‎devel-common/src/docs/provider_conf.py‎

Lines changed: 19 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,6 @@
3333
# serve to show the default.
3434
import logging
3535
import os
36-
from pathlib import Path
3736
from typing import Any
3837

3938
import rich
@@ -47,11 +46,14 @@
4746
AUTOAPI_OPTIONS,
4847
BASIC_AUTOAPI_IGNORE_PATTERNS,
4948
BASIC_SPHINX_EXTENSIONS,
50-
REDOC_SCRIPT_URL,
5149
SMARTQUOTES_EXCLUDES,
5250
SPELLING_WORDLIST_PATH,
5351
SPHINX_DESIGN_STATIC_PATH,
52+
SPHINX_SWAGGER_EXTENSION,
5453
SUPPRESS_WARNINGS,
54+
SWAGGER_BUNDLE_URI,
55+
SWAGGER_CSS_URI,
56+
SWAGGER_PRESENT_URI,
5557
filter_autoapi_ignore_entries,
5658
get_autodoc_mock_imports,
5759
get_configs_and_deprecations,
@@ -119,25 +121,21 @@
119121
# ones.
120122
extensions = BASIC_SPHINX_EXTENSIONS
121123

122-
PROVIDER_PACKAGES_WITH_REDOC = ["apache-airflow-providers-fab", "apache-airflow-providers-keycloak"]
123-
124-
if PACKAGE_NAME in PROVIDER_PACKAGES_WITH_REDOC:
125-
extensions.extend(
126-
[
127-
"autoapi.extension",
128-
# First, generate redoc
129-
"sphinxcontrib.redoc",
130-
# Second, update redoc script
131-
"sphinx_script_update",
132-
]
133-
)
134-
redoc_script_url = REDOC_SCRIPT_URL
135-
else:
136-
extensions.extend(
137-
[
138-
"autoapi.extension",
139-
]
140-
)
124+
PROVIDER_PACKAGES_WITH_API_REFERENCE = [
125+
"apache-airflow-providers-edge3",
126+
"apache-airflow-providers-fab",
127+
"apache-airflow-providers-keycloak",
128+
]
129+
130+
if PACKAGE_NAME in PROVIDER_PACKAGES_WITH_API_REFERENCE:
131+
extensions.append(SPHINX_SWAGGER_EXTENSION)
132+
133+
swagger_present_uri = SWAGGER_PRESENT_URI
134+
swagger_bundle_uri = SWAGGER_BUNDLE_URI
135+
swagger_css_uri = SWAGGER_CSS_URI
136+
swagger_mirror_external_resources = True # Ensure we embed external resources prevent tracking
137+
138+
extensions.append("autoapi.extension")
141139

142140
extensions.extend(
143141
[
@@ -357,38 +355,3 @@
357355
spelling_ignore_importable_modules = True
358356

359357
graphviz_output_format = "svg"
360-
361-
if PACKAGE_NAME in PROVIDER_PACKAGES_WITH_REDOC:
362-
from airflow.providers.fab.auth_manager.api_fastapi.openapi import (
363-
__file__ as fab_auth_manager_fastapi_api_file,
364-
)
365-
from airflow.providers.keycloak.auth_manager.openapi import (
366-
__file__ as keycloak_auth_manager_fastapi_api_file,
367-
)
368-
369-
fab_auth_manager_fastapi_api_path = Path(fab_auth_manager_fastapi_api_file).parent.joinpath(
370-
"v2-fab-auth-manager-generated.yaml"
371-
)
372-
keycloak_auth_manager_fastapi_api_path = Path(keycloak_auth_manager_fastapi_api_file).parent.joinpath(
373-
"v2-keycloak-auth-manager-generated.yaml"
374-
)
375-
redoc = [
376-
{
377-
"name": "Fab auth manager API",
378-
"page": "api-ref/fab-api-ref",
379-
"spec": fab_auth_manager_fastapi_api_path.as_posix(),
380-
"opts": {
381-
"hide-hostname": True,
382-
"no-auto-auth": True,
383-
},
384-
},
385-
{
386-
"name": "Keycloak auth manager token API",
387-
"page": "api-ref/token-api-ref",
388-
"spec": keycloak_auth_manager_fastapi_api_path.as_posix(),
389-
"opts": {
390-
"hide-hostname": True,
391-
"no-auto-auth": True,
392-
},
393-
},
394-
]

‎devel-common/src/docs/utils/conf_constants.py‎

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -97,15 +97,14 @@ def get_rst_epilogue(package_version: str, airflow_core: bool) -> str:
9797
"metrics_tables_from_registry",
9898
]
9999

100-
SPHINX_REDOC_EXTENSIONS = [
101-
"autoapi.extension",
102-
# First, generate redoc
103-
"sphinxcontrib.redoc",
104-
# Second, update redoc script
105-
"sphinx_script_update",
106-
]
107-
108-
REDOC_SCRIPT_URL = "https://cdn.jsdelivr.net/npm/[email protected]/bundles/redoc.standalone.js"
100+
# Properties for Swagger OpenAPI generation:
101+
# See https://github.com/SAP/swagger-plugin-for-sphinx
102+
SPHINX_SWAGGER_EXTENSION = "swagger_plugin_for_sphinx"
103+
104+
_SWAGGER_VERSION = "5.32.6"
105+
SWAGGER_PRESENT_URI = f"https://unpkg.com/swagger-ui-dist@{_SWAGGER_VERSION}/swagger-ui-standalone-preset.js"
106+
SWAGGER_BUNDLE_URI = f"https://unpkg.com/swagger-ui-dist@{_SWAGGER_VERSION}/swagger-ui-bundle.js"
107+
SWAGGER_CSS_URI = f"https://unpkg.com/swagger-ui-dist@{_SWAGGER_VERSION}/swagger-ui.css"
109108

110109

111110
def get_rst_filepath_from_path(filepath: pathlib.Path, root: pathlib.Path):
Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
2+
.. Licensed to the Apache Software Foundation (ASF) under one
3+
or more contributor license agreements. See the NOTICE file
4+
distributed with this work for additional information
5+
regarding copyright ownership. The ASF licenses this file
6+
to you under the Apache License, Version 2.0 (the
7+
"License"); you may not use this file except in compliance
8+
with the License. You may obtain a copy of the License at
9+
10+
.. http://www.apache.org/licenses/LICENSE-2.0
11+
12+
.. Unless required by applicable law or agreed to in writing,
13+
software distributed under the License is distributed on an
14+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
KIND, either express or implied. See the License for the
16+
specific language governing permissions and limitations
17+
under the License.
18+
19+
Edge Worker REST API
20+
====================
21+
22+
.. swagger-plugin:: ../src/airflow/providers/edge3/worker_api/v2-edge-generated.yaml
23+
:id: edge-worker-api-ref
24+
:page-title: Edge Worker REST API
25+
:swagger-options: { "tryItOutEnabled": "false", "supportedSubmitMethods": [] }

‎providers/edge3/docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@
5858
Configuration <configurations-ref>
5959
CLI <cli-ref>
6060
Python API <_api/airflow/providers/edge3/index>
61+
Edge Worker REST API <edge-api-ref>
6162

6263
.. toctree::
6364
:hidden:

0 commit comments

Comments
 (0)