Start building openapi doc

- Build openapi spec as part of the api-ref job
- render openapi as separate doc (preview)

Change-Id: Ib100f1943e223f30fd5ff53042b3f5f5bae2dd25

.gitignore

@@ -44,3 +44,6 @@ etc/keystone.conf.sample
 # sample policy file included in docs
 doc/source/_static/keystone.policy.yaml.sample
 etc/keystone.policy.yaml.sample
+
+# openapi specs in the api-ref are built dynamically
+api-ref/source/openapi/v*.yaml

api-ref/requirements.txt

@@ -0,0 +1,4 @@
+# os-openapi is installed directly from git since we do not do releases (yet?)
+os-openapi @ git+https://opendev.org/openstack/openapi
+
+os-api-ref>=1.4.0 # Apache-2.0

api-ref/source/conf.py

@@ -25,7 +25,7 @@
 html_theme = 'openstackdocs'
 html_theme_options = {"sidebar_dropdown": "api_ref", "sidebar_mode": "toc"}
 
-extensions = ['os_api_ref', 'openstackdocstheme']
+extensions = ['os_api_ref', 'openstackdocstheme', 'os_openapi']
 
 
 # If extensions (or modules to document with autodoc) are in another directory,

api-ref/source/index.rst

@@ -10,6 +10,11 @@ Contents:
     v3/index
     v3-ext/index
 
+.. toctree::
+    :maxdepth: 1
+
+    openapi
+
 Indices and tables
 ==================
 

api-ref/source/openapi.rst

@@ -0,0 +1,5 @@
+Keystone OpenAPI specification (preview)
+========================================
+
+.. openapi:: openapi/v3.yaml
+   :service_type: identity

doc/requirements.txt

@@ -6,6 +6,5 @@ sphinx>=2.0.0,!=2.1.0 # BSD
 sphinxcontrib-apidoc>=0.2.0  # BSD
 sphinx-feature-classification>=0.3.2  # Apache-2.0
 reno>=3.1.0 # Apache-2.0
-os-api-ref>=1.4.0 # Apache-2.0
 python-ldap>=3.0.0  # PSF
 ldappool>=2.0.0 # MPL

tox.ini

@@ -136,9 +136,21 @@ deps = {[testenv:docs]deps}
 commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
 
 [testenv:api-ref]
-deps = {[testenv:docs]deps}
+deps =
+  {[testenv:docs]deps}
+  -r{toxinidir}/api-ref/requirements.txt
+allowlist_externals =
+  bash
+  mkdir
+  cp
 commands =
   bash -c "rm -rf api-ref/build"
+  # OpenStack is terribly slow on getting latest versions so this need to be
+  # installed separately due to the necessary pydantic version
+  pip install openstack-codegenerator@git+https://opendev.org/openstack/codegenerator
+  openstack-codegenerator --work-dir wrk --target openapi-spec --service-type identity
+  bash -c "mkdir -p api-ref/source/openapi"
+  bash -c "cp -av wrk/openapi_specs/identity/* api-ref/source/openapi"
   sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
 
 [testenv:genconfig]