Merge pull request #3660 from lcaouen/new_swagger_generation

New swagger generation

Author: georgweiss

.github/workflows/build_swagger.yml

@@ -8,6 +8,7 @@ dependencies = [
     "sphinx_rtd_theme>=3.0",
     "myst-parser>=4.0",
     "setuptools",
+    "sphinxcontrib.openapi"
 ]
 
 [tool.pixi.workspace]

docs/pyproject.toml

@@ -0,0 +1,37 @@
+import os
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from sphinx.util.nodes import nested_parse_with_titles
+
+class SafeOpenApiDirective(Directive):
+    """
+    Usage :
+        .. safe_openapi:: path/to/openapi.yaml
+    """
+    required_arguments = 1
+
+    def run(self):
+        env = self.state.document.settings.env
+        docdir = os.path.dirname(env.doc2path(env.docname))
+
+        # Argument from the directive
+        openapi_path = self.arguments[0]
+
+        # Find absolute path
+        full_path = os.path.normpath(os.path.join(docdir, openapi_path))
+
+        if os.path.exists(full_path):
+            # add the normal `openapi` directive
+            node = nodes.paragraph()
+            directive_text = f".. openapi:: {openapi_path}\n"
+            self.state_machine.insert_input([directive_text], self.state_machine.input_lines.source(0))
+            return []
+        else:
+            # add file not found
+            warning = nodes.paragraph(text=f"OpenAPI file {openapi_path} not found")
+            return [warning]
+
+
+def setup(app):
+    app.add_directive("safe_openapi", SafeOpenApiDirective)
+    return {"version": "1.0"}

docs/source/_ext/safe_openapi.py

@@ -30,8 +30,10 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+	"sphinxcontrib.openapi",
     "myst_parser",
     "preferences_listing",
+    "safe_openapi"
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/conf.py

@@ -47,4 +47,10 @@ The automatic purge is run using a cron expression defined in preference ``purge
 An Elasticsearch index is considered eligible for deletion if the last inserted message date is before current time
 minus the number of days computed from ``date_span_units`` and ``retain_indices_count``.
 
+***
+API
+***
+.. safe_openapi:: ../../../../../services/alarm-logger/target/spec-open-api.json
+
+
 .. _SpringDocumentation: https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/scheduling/support/CronExpression.html

services/alarm-logger/doc/index.rst

@@ -173,6 +173,49 @@
               </execution>
             </executions>
           </plugin>
+          <!-- Plugin declaration -->
+          <plugin>
+            <groupId>io.github.kbuntrock</groupId>
+            <artifactId>openapi-maven-plugin</artifactId>
+            <version>0.0.28</version>
+            <executions>
+              <execution>
+                <id>documentation</id>
+                <goals>
+                  <goal>documentation</goal>
+                </goals>
+              </execution>
+            </executions>
+            <configuration>
+              <!-- This section defines the general configuration, which can be overriden for each generated document. -->
+              <apiConfiguration>
+                <library>SPRING_MVC</library> <!-- SPRING_MVC is the default value. Here this tag could be deleted. Other possible values are JAKARTA_RS and JAVAX_RS -->
+                <fileFormat>json</fileFormat>
+                <tagAnnotations> <!-- Only useful if you use Spring MVC -->
+                  <!-- RestController is the default value, but can be replaced by RequestMapping -->
+                  <annotation>RestController</annotation>
+                </tagAnnotations>
+              </apiConfiguration>
+              <!-- This section defines which folders contains the source code to be read to extract the javadoc. -->
+              <javadocConfiguration>
+                <scanLocations>
+                  <!-- Other 'location' tag can be added to reference javadoc in other modules. -->
+                  <!-- Path is relative to the project root path. -->
+                  <location>src/main/java</location>
+                </scanLocations>
+              </javadocConfiguration>
+              <!-- This section defines a list of documentations to generate. In this exemple, only one is generated. -->
+              <apis>
+                <api>
+                  <locations>
+                    <!-- Replace here by a package relevant for your project. -->
+                    <location>org.phoebus.alarm.logging</location>
+                  </locations>
+                </api>
+              </apis>
+            </configuration>
+          </plugin>
+
         </plugins>
       </build>
     </profile>

services/alarm-logger/pom.xml

@@ -103,7 +103,7 @@ public List<AlarmLogMessage> search(@Parameter(hidden = true) @RequestParam Map<
 
     @Operation(summary = "Search alarms by PV name")
     @RequestMapping(value = "/search/alarm/pv/{pv}", method = RequestMethod.GET)
-    public List<AlarmLogMessage> searchPv(@Parameter(description = "PV name") @PathVariable String pv) {
+    public List<AlarmLogMessage> searchPv(@Parameter(name="pv", description = "PV name") @PathVariable String pv) {
         Map<String, String> searchParameters = new HashMap<>();
         searchParameters.put("pv", pv);
         List<AlarmLogMessage> result = AlarmLogSearchUtil.search(ElasticClientHelper.getInstance().getClient(), searchParameters);