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

  Branch: refs/heads/release-36.x
  Home:   https://github.com/OpenNMS/opennms
  Commit: c580f0d16af06c38b7e843d1656418b127387eb9
      https://github.com/OpenNMS/opennms/commit/c580f0d16af06c38b7e843d1656418b127387eb9
  Author: Marshall Massengill <[email protected]>
  Date:   2026-08-11 (Tue, 11 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/java/org/opennms/openapi/OpenApiDocGenerator.java
    A opennms-openapi-docs/src/main/java/org/opennms/openapi/OpenApiDocWriter.java
    A opennms-openapi-docs/src/test/java/org/opennms/openapi/OpenApiDocsContentTest.java
    A opennms-openapi-docs/src/test/java/org/opennms/openapi/OpenApiResourceCoverageTest.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
    M opennms-webapp-rest/src/main/webapp/WEB-INF/menu/menu-template-alt.json
    M opennms-webapp-rest/src/main/webapp/WEB-INF/menu/menu-template-default.json
    M opennms-webapp-rest/src/main/webapp/WEB-INF/menu/menu-template.json
    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
    M smoke-test/src/test/java/org/opennms/smoketest/MenuHeaderIT.java
    A smoke-test/src/test/java/org/opennms/smoketest/rest/OpenApiRestIT.java
    M ui/src/containers/OpenAPI.vue
    M ui/tests/containers/OpenAPI.test.ts
    A ui/tests/containers/OpenAPIFetch.test.ts

  Log Message:
  -----------
  NMS-20163: Generate the OpenAPI documents at build time (#8743)

* 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.

* NMS-20163: Move OpenApiDocGenerator to src/main/java

The generator is build tooling, not a test, so it does not belong in test
sources. Its dependencies move from test to provided scope: the generator
compiles against them and needs them to load the ReST resource classes,
while provided scope keeps them out of anything that consumes this
artifact, so the shipped jar still carries only the generated JSON.

* NMS-20163: Trim the openapi-docs README

Drop the 'Adding a ReST module' section; the pom comment and
OpenApiDocsContentTest already carry those facts. Note the build
prerequisite for regenerating.

* NMS-20163: Generate the OpenAPI documents at build time

Bind OpenApiDocWriter to process-classes and drop the committed documents,
so there is nothing to regenerate by hand, conflict on a forward merge, or
hold up a release.

* NMS-20163: Fail the build when a ReST module is missing from this pom

Walk the source tree for type-level @Path classes under org.opennms.web.rest.v1
and .v2 and check each one resolves on this module's classpath. A contributing
module that is not a dependency here still generates a valid document, just one
without its endpoints.

* NMS-20163: Check ReST coverage per module rather than per class

@Path is often inherited from an interface in org.opennms.web.rest.v2.api,
which reading the class declaration in source cannot see; six resources were
being skipped. Checking that each module contributing ReST sources resolves
on the classpath needs no annotation parsing and is what catches a missing
dependency.

Locate the repository root by walking up for a marker, so moving this module
does not silently break the scan. -Dopennms.repoRoot overrides it.

* NMS-20163: Refuse to generate the documents outside a forked JVM

Run by exec:java rather than exec:exec, the generator is loaded by a plugin
realm, part of the project classpath is shadowed, and one schema silently
loses its xml metadata while every test still passes. Check the class loader
and fail instead.

Also resolve the java executable per platform, drop the environment-specific
directory from the source scan in favour of skipping dot directories, allow a
module to be exempted from the coverage check, and raise the path-count floors
from 150 against actual counts of 199 and 223.

* NMS-20163: Fix the OpenAPI docs page layout, fonts and resize cost

The app shell overflows the viewport by 16px whatever this page does, and
that is enough for RapiDoc's scrollIntoView to drag the whole layout as the
content passes a section. Clip the page while the column fits and pin the
offset, since a clipped viewport still scrolls programmatically.

RapiDoc writes an inline width:100vw/height:100vh onto the panel holding it,
which put the V1 doc 214px past the clipped column and its scrollbar out of
reach; override the panel size.

render-style focused rather than read, which lays out only the selected
operation: a horizontal resize drops from ~2900ms to ~35ms with the nav
kept. load-fonts false stops RapiDoc fetching Open Sans from Google at
runtime, matching the stack the app already declares.

Move the in-flight fetch test to its own file: it needs vi.resetModules(),
after which happy-dom stops applying style writes for the rest of the file.

* NMS-20163: Call the OpenAPI page the same thing everywhere

The menu said 'REST Open API Documentation' and the breadcrumb 'Open API
Docs', so clicking through landed on a page that named itself something
else. Both are now 'OpenAPI Documentation', which is also the spelling the
OpenAPI Initiative uses. The parent menu is already 'API Documentation', so
the REST prefix was not what distinguished this item from its sibling.

* NMS-20163: Open the OpenAPI page on the first operation

Focused mode opens on the info section, which left most of the pane empty next
to the endpoint list. Turn it off so the first operation is what renders.

The generated documents also described themselves with a copy of their own
title. Give each one a description that says something.

* NMS-20163: Redirect api-docs to api-docs/

index.html is served at both spellings, but it names its assets and its
spec URL relative to itself, so from the slash-less one they all resolve
a directory too high and the page comes up broken. Every link we ship
carries the slash, so this is only reachable by typing the URL.

* NMS-20163: Keep the generator off the Windows command line limit

The forked generator was handed the whole project classpath inline after
-classpath, which on this project runs past the 32K that CreateProcess
accepts, so the build failed on Windows before the JVM started.
longClasspath moves the classpath into the manifest of a generated jar;
the documents come out byte-identical, and the fork check still holds
because the pathing jar is still loaded by the system class loader.

* NMS-20163: Cover the OpenAPI endpoints with a smoke test

The documents and the Swagger UI are read off the classpath, and the
resources serving them answer 404 rather than failing when they are
absent. Nothing short of a request against a running instance notices a
packaging slip, such as the documents jar dropping out of webapp-full.
This replaces the OpenApiIT that generation at build time made obsolete,
which ran in-process against a classpath that no longer carries the
documents.



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