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

  Branch: refs/heads/mm/NMS-20163-smoke
  Home:   https://github.com/OpenNMS/opennms
  Commit: 756f85ce0aa7afa165aa2b2e06f09c884911af5e
      https://github.com/OpenNMS/opennms/commit/756f85ce0aa7afa165aa2b2e06f09c884911af5e
  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 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.
- OpenApiDocsUpToDateTest fails the build when a ReST change leaves them stale;
  refresh with -Dopenapi.regenerate=true.
- First request to openapi.json drops from ~1.3s to under 0.1s.
- WEB-INF/lib loses classgraph, jvm-driver, narcissus, swagger-jaxrs2,
  swagger-integration and three cxf-rt-rs-service-description artifacts.
- Swagger UI keeps its api-docs/ paths, now served by a resource of our own
  rather than by the feature. Two fixes come with that: the webjar's favicons
  returned 404, because CXF's media-type map has no png entry, and api-docs/
  with no query parameter fell back to the Swagger petstore spec.


  Commit: 87aae63e77434cceb1b71a06437fae96dc339ea4
      https://github.com/OpenNMS/opennms/commit/87aae63e77434cceb1b71a06437fae96dc339ea4
  Author: Marshall Massengill <[email protected]>
  Date:   2026-08-05 (Wed, 05 Aug 2026)

  Changed paths:
    M opennms-webapp-rest/src/main/java/org/opennms/web/rest/support/openapi/AbstractSwaggerUiResource.java
    M opennms-webapp-rest/src/test/java/org/opennms/web/rest/support/openapi/SwaggerUiResourceTest.java
    M opennms-webapp/src/main/webapp/includes/help-documentation.jsp
    M pom.xml

  Log Message:
  -----------
  NMS-20163: Move Swagger UI to 5.25.3 and stop honouring ?url=

swagger-ui 3.23.11 merges the page's query string over its constructor options,
so ?url= selects which OpenAPI document the browser fetches. That is the subject
of GHSA-qrmm-w75w-3wpx and CVE-2018-25031, both fixed in 4.1.3 by not reading
config from the query string; 3.23.11 was the last version still doing it.

- Bumps the webjar from 3.23.11, set by NMS-16546 to pick up the CVE-2019-17495
  fix, to 5.25.3.
- 5.x moves the spec URL out of index.html into swagger-initializer.js, which the
  browser fetches without a query string, so the resource rewrites that file
  instead and always points at the sibling openapi.json.
- Drops the now-inert ?url= from the help page link. It resolved to the same
  document the default does.
- Removes the ability to point one context's UI at another document, which is
  what ?url= was used for on the help page. Each ReST context serves its own
  api-docs/ and openapi.json.
- The webjar shrinks from 3.0 MB to 1.1 MB; it no longer ships .gz or .map files.


Compare: https://github.com/OpenNMS/opennms/compare/756f85ce0aa7%5E...87aae63e7743

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