[OpenNMS/opennms] 8a78e7: NMS-20163: Generate the OpenAPI documents at build...

  Branch: refs/heads/mm/NMS-20163-smoke
  Home:   https://github.com/OpenNMS/opennms
  Commit: 8a78e762d3ab6bd725017bdf4ced6f1d550d3f58
      https://github.com/OpenNMS/opennms/commit/8a78e762d3ab6bd725017bdf4ced6f1d550d3f58
  Author: Marshall Massengill <[email protected]>
  Date:   2026-08-05 (Wed, 05 Aug 2026)

  Changed paths:
    M opennms-assemblies/webapp-full/pom.xml
    A opennms-openapi-docs/README.adoc
    A opennms-openapi-docs/pom.xml
    A opennms-openapi-docs/src/main/resources/openapi/openapi-v1.json
    A opennms-openapi-docs/src/main/resources/openapi/openapi-v2.json
    A opennms-openapi-docs/src/test/java/org/opennms/openapi/OpenApiDocGenerator.java
    A opennms-openapi-docs/src/test/java/org/opennms/openapi/OpenApiDocsContentTest.java
    A opennms-openapi-docs/src/test/java/org/opennms/openapi/OpenApiDocsUpToDateTest.java
    M opennms-webapp-rest/pom.xml
    A opennms-webapp-rest/src/main/java/org/opennms/web/rest/support/openapi/AbstractStaticOpenApiResource.java
    A opennms-webapp-rest/src/main/java/org/opennms/web/rest/support/openapi/AbstractSwaggerUiResource.java
    A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/OpenApiResource.java
    A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/SwaggerUiResource.java
    A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/OpenApiResource.java
    A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/SwaggerUiResource.java
    A opennms-webapp-rest/src/main/resources/openapi/swagger-ui.properties
    M opennms-webapp-rest/src/main/webapp/WEB-INF/applicationContext-cxf-rest-v1.xml
    M opennms-webapp-rest/src/main/webapp/WEB-INF/applicationContext-cxf-rest-v2.xml
    A opennms-webapp-rest/src/test/java/org/opennms/web/rest/support/openapi/StaticOpenApiResourceTest.java
    A opennms-webapp-rest/src/test/java/org/opennms/web/rest/support/openapi/SwaggerUiResourceTest.java
    R opennms-webapp-rest/src/test/java/org/opennms/web/rest/v2/OpenApiIT.java
    A opennms-webapp-rest/src/test/resources/openapi/openapi-stub.json
    M opennms-webapp/src/main/webapp/includes/help-documentation.jsp
    M pom.xml

  Log Message:
  -----------
  NMS-20163: Generate the OpenAPI documents at build time

Both CXF servlets registered OpenApiFeature, which ran swagger-jaxrs2's reader over
every deployed resource class on the first request to openapi.json. The new
opennms-openapi-docs module generates the v1 and v2 documents during the build and
commits them; OpenApiResource serves them from the classpath.

- The committed documents are canonically identical to what the runtime produced,
  checked against a pristine release-36.x instance: v1 is 199 paths and 152 schemas,
  v2 is 223 and 104. Raw text differs only in key ordering inside objects, because
  the generator sorts the resource classes for determinism where CXF used its scan
  order.
- OpenApiDocsUpToDateTest fails the build when a ReST change leaves the committed
  documents stale; refresh with -Dopenapi.regenerate=true. A module contributing
  classes to org.opennms.web.rest.v1 or .v2 has to be a test-scope dependency of
  opennms-openapi-docs, and OpenApiDocsContentTest guards the five that exist today.
- First request to openapi.json drops from ~1.3s to under 0.05s.
- Eight jars leave WEB-INF/lib: swagger-jaxrs2, swagger-integration, classgraph,
  jvm-driver, narcissus and the three cxf-rt-rs-service-description artifacts. One
  arrives, opennms-openapi-docs at 51 KB.
- Swagger UI keeps its api-docs paths, now served by a resource of our own rather
  than by the feature, and moves from 3.23.11 to 5.25.3. 3.23.11 merges the page's
  query string over its constructor options, so ?url= chose which document the
  browser fetched, which is GHSA-qrmm-w75w-3wpx and CVE-2018-25031, both fixed in
  4.1.3. That removes the ability to point one context's UI at another document;
  each context serves its own, so the help page link is unaffected. The webjar drops
  from 3.0 MB to 1.1 MB, and the favicons that used to 404 no longer do.



To unsubscribe from these emails, change your notification settings at https://github.com/OpenNMS/opennms/settings/notifications


_______________________________________________
Please read the OpenNMS Mailing List FAQ:
http://www.opennms.org/wiki/index.php?page=MailingListFaq
opennms-cvs mailing list

To *unsubscribe* or change your subscription options, see the bottom of this page:
https://lists.sourceforge.net/lists/listinfo/opennms-cvs