diff --git a/.gitignore b/.gitignore
index 3cfa954b36..f7e770bd8d 100644
--- a/.gitignore
+++ b/.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
diff --git a/api-ref/requirements.txt b/api-ref/requirements.txt
new file mode 100644
index 0000000000..15e2471881
--- /dev/null
+++ b/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
diff --git a/api-ref/source/conf.py b/api-ref/source/conf.py
index 38a34b99d3..8b691412c8 100644
--- a/api-ref/source/conf.py
+++ b/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,
diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index d42f48cc42..f7c569be1d 100644
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@@ -10,6 +10,11 @@ Contents:
     v3/index
     v3-ext/index
 
+.. toctree::
+    :maxdepth: 1
+
+    openapi
+
 Indices and tables
 ==================
 
diff --git a/api-ref/source/openapi.rst b/api-ref/source/openapi.rst
new file mode 100644
index 0000000000..c6fcc3faba
--- /dev/null
+++ b/api-ref/source/openapi.rst
@@ -0,0 +1,5 @@
+Keystone OpenAPI specification (preview)
+========================================
+
+.. openapi:: openapi/v3.yaml
+   :service_type: identity
diff --git a/doc/requirements.txt b/doc/requirements.txt
index b7023fe12e..a313b79d7c 100644
--- a/doc/requirements.txt
+++ b/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
diff --git a/tox.ini b/tox.ini
index 0cdea4e859..0e572e6b07 100644
--- a/tox.ini
+++ b/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]