Add additional API documentation

Issue-ID: SMO-155 Change-Id: I943d950ea14f7eb6b57167d5d94c742a58cf687b Signed-off-by: JohnKeeney <[email protected]>
o-ran-sc · Jul 9, 2024 · 669c648 · 669c648
1 parent ea1ce62
commit 669c648
Show file tree

Hide file tree

Showing 14 changed files with 29,345 additions and 14 deletions.
diff --git a/.gitignore b/.gitignore
@@ -22,7 +22,6 @@ target
 /.metadata/
 **/.sts4-cache
 **/.java-version
-index.html
 **/.openapi-generator
 .openapi-generator-ignore
 yang-parser/src/main/resources/modules/*.yang
@@ -31,6 +30,9 @@ yang-parser/src/test/resources/_orig-modules/_3gpp*.yang
 yang-parser/src/test/resources/_orig-modules/iana*.yang
 pgsql-schema-generator/src/test/resources/generate-defaults/import/*.yang
 teiv/src/main/resources/models/import/*.yang
-
+teiv/src/main/resources/v1/README.md
+teiv/src/main/resources/v1/index.html
+teiv/src/main/resources/v1/html/
+teiv/src/main/resources/v1/topology-exposure-inventory-openapi.json
 .tox
 docs/_build
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -26,7 +26,12 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
-
+  jobs:
+    post_build:
+      - cp -v docs/offeredapis/html/index.html $READTHEDOCS_OUTPUT/html/offeredapis/html
+      - cp -v docs/offeredapis/index.html $READTHEDOCS_OUTPUT/html/offeredapis/
+      - cp -v docs/offeredapis/topology-exposure-inventory-openapi.yaml $READTHEDOCS_OUTPUT/html/offeredapis/
+      - cp -v docs/offeredapis/topology-exposure-inventory-openapi.json $READTHEDOCS_OUTPUT/html/offeredapis/
 python:
   install:
   - requirements: docs/requirements-docs.txt

diff --git a/docs/_static/swagger.png b/docs/_static/swagger.png
diff --git a/docs/_static/yaml_logo.png b/docs/_static/yaml_logo.png
diff --git a/docs/api-documentation.rst b/docs/api-documentation.rst
@@ -5,7 +5,37 @@
 
 .. _api:
 
-APIs
-====
+Offered APIs
+============
+
+API Table
+---------
+
+.. |swagger-icon| image:: ./_static/swagger.png
+                  :width: 40px
+
+.. |yaml-icon| image:: ./_static/yaml_logo.png
+                  :width: 40px
+
+
+.. csv-table::
+   :header: "API name", "|swagger-icon|", "|yaml-icon|"
+   :widths: 10,5, 5
+
+   "Topology Exposure & Inventory Service API (NBI)", ":download:`link <./offeredapis/topology-exposure-inventory-openapi.json>`", ":download:`link <./offeredapis/topology-exposure-inventory-openapi.yaml>`"
+
+.. _pms_api:
+
+Topology Exposure & Inventory Service API
+-----------------------------------------
+
+The Topology Exposure & Inventory Service API is described in more detail in:
+
+* `Topology Exposure & Inventory Service API (html) (1) <./offeredapis/topology-exposure-inventory-openapi.html>`_
+* `Topology Exposure & Inventory Service API (html) (2) <./offeredapis/index.html>`_
+* `Topology Exposure & Inventory Service API (html) (3) <./offeredapis/html/index.html>`_
+
+Topology Exposure & Inventory Service API (Summary)
+....................................................
 
 .. openapi:: ../teiv/src/main/resources/v1/topology-exposure-inventory-openapi.yaml
diff --git a/docs/conf.py b/docs/conf.py
@@ -27,5 +27,24 @@
 
 extensions = [
     'sphinx.ext.autosectionlabel',
-    'sphinxcontrib.openapi'
+    'sphinxcontrib.openapi',
+    'sphinxcontrib.redoc'
+]
+
+redoc = [
+            {
+                'name': 'Topology Exposure & Inventory Service API',
+                'page': 'offeredapis/topology-exposure-inventory-openapi',
+                'spec': './offeredapis/topology-exposure-inventory-openapi.yaml',
+                'embed': True,
+            }
+]
+html_extra_path = [
+]
+
+linkcheck_ignore = [
+  r'http://localhost:\d+/',
+  './offeredapis/topology-exposure-inventory-openapi.html',  #Generated file that doesn't exist at link check.
+  './offeredapis/index.html',  #Generated file that doesn't exist at link check.
+  './offeredapis/html/index.html'  #Generated file that doesn't exist at link check.
 ]
diff --git a/docs/offeredapis/html/index.html b/docs/offeredapis/html/index.html
diff --git a/docs/offeredapis/index.html b/docs/offeredapis/index.html
diff --git a/docs/offeredapis/topology-exposure-inventory-openapi.json b/docs/offeredapis/topology-exposure-inventory-openapi.json
diff --git a/docs/offeredapis/topology-exposure-inventory-openapi.yaml b/docs/offeredapis/topology-exposure-inventory-openapi.yaml
diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
@@ -3,5 +3,6 @@ sphinx
 doc8
 docutils
 sphinxcontrib-openapi
+sphinxcontrib-redoc
 lfdocs-conf
 urllib3~=1.26.15
diff --git a/pom.xml b/pom.xml
@@ -80,7 +80,7 @@
         <version.mockitoinline>5.2.0</version.mockitoinline>
         <version.testcontainers>1.18.0</version.testcontainers>
         <!-- Plugin Dependencies -->
-        <version.openapi-generator-maven-plugin>6.5.0</version.openapi-generator-maven-plugin>
+        <version.openapi-generator-maven-plugin>7.7.0</version.openapi-generator-maven-plugin>
         <version.spotless-plugin>2.30.0</version.spotless-plugin>
         <version.contract-documentation-generator-mvn-plugin>1.0.1</version.contract-documentation-generator-mvn-plugin>
         <version.asciidoctor-maven-plugin>2.2.1</version.asciidoctor-maven-plugin>
@@ -130,6 +130,8 @@
                                     <exclude>generated*/</exclude>
                                     <exclude>dependencies/*</exclude>
                                     <exclude>dependencies*/</exclude>
+                                    <exclude>teiv/src/main/resources/v1/**/*.html</exclude>
+                                    <exclude>teiv/src/main/resources/v1/topology-exposure-inventory-openapi.json</exclude>
                                 </excludes>
                             </licenseSet>
                         </licenseSets>
@@ -184,6 +186,8 @@
                             <excludes>
                                 <exclude>target/**/*.json</exclude>
                                 <exclude>build/**/*.json</exclude>
+                                <!--generated -->
+                                <exclude>**/resources/v1/topology-exposure-inventory-openapi.json</exclude> 
                             </excludes>
                             <eclipseWtp>
                                 <type>JSON</type>

diff --git a/teiv/pom.xml b/teiv/pom.xml
@@ -231,8 +231,7 @@
             </testResource>
         </testResources>
         <plugins>
-            <!-- TODO internaltools.devops plugin which generates .adoc of contract
-                test -->
+            <!-- TODO Need a plugin which generates .adoc of contract tests -->
             <plugin>
                 <groupId>org.asciidoctor</groupId>
                 <artifactId>asciidoctor-maven-plugin</artifactId>
@@ -258,18 +257,58 @@
                 <executions>
                     <execution>
                         <id>openapi-generate-html</id>
+                        <phase>generate-sources</phase>
                         <goals>
                             <goal>generate</goal>
                         </goals>
                         <configuration>
-                            <inputSpec>
-                                ${project.basedir}/src/main/resources/v1/topology-exposure-inventory-openapi.yaml</inputSpec>
+                            <inputSpec>${project.basedir}/src/main/resources/v1/topology-exposure-inventory-openapi.yaml</inputSpec>
                             <generatorName>html</generatorName>
                             <output>src/main/resources/v1</output>
                         </configuration>
                     </execution>
+                    <execution>
+                        <id>generate-openapi-html2</id>
+                        <phase>generate-sources</phase>
+                        <goals>
+                            <goal>generate</goal>
+                        </goals>
+                        <configuration>
+                            <inputSpec>${project.basedir}/src/main/resources/v1/topology-exposure-inventory-openapi.yaml</inputSpec>
+                            <generatorName>html2</generatorName>
+                            <output>src/main/resources/v1/html</output>
+                            <skipOperationExample>false</skipOperationExample>
+                            <strictSpec>false</strictSpec>
+                            <configOptions>
+                                <appDescription>The O-RAN Topology Exposure &amp; Inventory
+                                    manages the representation of topology and inventory resource</appDescription>
+                                <appName>O-RAN SC - Topology Exposure &amp; Inventory</appName>
+                                <infoUrl>https://wiki.o-ran-sc.org/pages/viewpage.action?pageId=125042884</infoUrl>
+                                <licenseInfo>Copyright (C) 2024 Ericsson,
+                                    Modifications Copyright (C) 2024 OpenInfra Foundation Europe.
+                                    All rights reserved.</licenseInfo>
+                                <licenseUrl>http://www.apache.org/licenses/LICENSE-2.0</licenseUrl>
+                            </configOptions>
+                        </configuration>
+                    </execution>
+                    <execution>
+                        <id>generate-openapi-json</id>
+                        <phase>generate-sources</phase>
+                        <goals>
+                            <goal>generate</goal>
+                        </goals>
+                        <configuration>
+                            <inputSpec>${project.basedir}/src/main/resources/v1/topology-exposure-inventory-openapi.yaml</inputSpec>
+                            <generatorName>openapi</generatorName>
+                            <output>src/main/resources/v1</output>
+                            <configOptions>
+                                <outputFileName>topology-exposure-inventory-openapi.json</outputFileName>
+                            </configOptions>
+                        </configuration>
+                    </execution>
                     <execution>
                         <id>openapi-generate-pojos</id>
+                        <phase>generate-sources</phase>
                         <goals>
                             <goal>generate</goal>
                         </goals>
@@ -304,6 +343,33 @@
                     </execution>
                 </executions>
             </plugin>
+            <plugin>
+                <artifactId>maven-resources-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>copy-resource-docs</id>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>copy-resources</goal>
+                        </goals>
+                        <configuration>
+                            <outputDirectory>${project.basedir}/../docs/offeredapis/</outputDirectory>
+                            <overwrite>true</overwrite>
+                            <resources>
+                                <resource>
+                                    <directory>${project.basedir}/src/main/resources/v1</directory>
+                                    <includes>
+                                        <include>topology-exposure-inventory-openapi.yaml</include>
+                                        <include>topology-exposure-inventory-openapi.json</include>
+                                        <include>index.html</include>
+                                        <include>html/index.html</include>
+                                    </includes>
+                                </resource>
+                            </resources>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
             <plugin>
                 <groupId>org.springframework.boot</groupId>
                 <artifactId>spring-boot-maven-plugin</artifactId>

diff --git a/tox.ini b/tox.ini
@@ -27,11 +27,9 @@ skipsdist = true
 [testenv:docs]
 basepython = python3
 deps = -r{toxinidir}/docs/requirements-docs.txt
-
 commands =
     sphinx-build -W -b html -n -d {envtmpdir}/docs/doctrees ./docs/ {toxinidir}/docs/_build/html
-    echo "Generated docs available in {toxinidir}/docs/_build/html"
-allowlist_externals = echo
+    # Generated docs available in {toxinidir}/docs/_build/html
 
 [testenv:docs-linkcheck]
 basepython = python3