[OpenNMS/opennms] 51129e: NMS-20263: Add swagger-annotations to the ReST mod...
Marshall Massengill via opennms-cvs <[email protected]>
| Newsgroups | gmane.network.opennms.cvs |
|---|---|
| Message-ID | <OpenNMS/opennms/push/refs/heads/mm/NMS-20263-smoke/[email protected]> |
Branch: refs/heads/mm/NMS-20263-smoke
Home: https://github.com/OpenNMS/opennms
Commit: 51129eb79e591d5b40cc1baf0d55f504456bedaf
https://github.com/OpenNMS/opennms/commit/51129eb79e591d5b40cc1baf0d55f504456bedaf
Author: Marshall Massengill <[email protected]>
Date: 2026-08-26 (Wed, 26 Aug 2026)
Changed paths:
M features/bsm/rest/api/pom.xml
M features/bsm/rest/impl/pom.xml
M features/geolocation/rest/pom.xml
M features/measurements/api/pom.xml
M features/measurements/rest/pom.xml
M features/rest/model/pom.xml
M features/status/rest/pom.xml
Log Message:
-----------
NMS-20263: Add swagger-annotations to the ReST modules that lacked it
Seven modules carry JAX-RS resources or their DTOs but had no
swagger-annotations dependency, so their operations could not be annotated
at all. Scope is provided: the jar already ships in the webapp's WEB-INF/lib.
Commit: 0f78db6b25086131ed5d167a75e5ca5179a632df
https://github.com/OpenNMS/opennms/commit/0f78db6b25086131ed5d167a75e5ca5179a632df
Author: Marshall Massengill <[email protected]>
Date: 2026-08-26 (Wed, 26 Aug 2026)
Changed paths:
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/BusinessServiceListDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/BusinessServiceRequestDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/BusinessServiceResponseDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/MapFunctionDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/ReduceFunctionDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/edge/AbstractEdgeRequestDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/edge/AbstractEdgeResponseDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/edge/ApplicationEdgeRequestDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/edge/ApplicationEdgeResponseDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/edge/ApplicationResponseDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/edge/ChildEdgeRequestDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/edge/ChildEdgeResponseDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/edge/IpServiceEdgeRequestDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/edge/IpServiceEdgeResponseDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/edge/IpServiceResponseDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/edge/ReductionKeyEdgeRequestDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/edge/ReductionKeyEdgeResponseDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/meta/FunctionMetaDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/meta/FunctionMetaListDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/meta/ParameterMetaDTO.java
M features/bsm/rest/impl/src/main/java/org/opennms/web/rest/v2/bsm/BusinessServiceRestService.java
M features/geolocation/rest/src/main/java/org/opennms/web/rest/v2/GeolocationQueryDTO.java
M features/geolocation/rest/src/main/java/org/opennms/web/rest/v2/GeolocationRestService.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/BridgeElementNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/BridgeLinkNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/BridgeLinkRemoteNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/CdpElementNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/CdpLinkNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/EnlinkdDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/IsisElementNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/IsisLinkNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/LldpElementNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/LldpLinkNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/OspfElementNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/OspfLinkNodeDTO.java
M features/status/rest/src/main/java/org/opennms/web/rest/v2/status/StatusRestService.java
M features/status/rest/src/main/java/org/opennms/web/rest/v2/status/model/ApplicationDTOList.java
M features/status/rest/src/main/java/org/opennms/web/rest/v2/status/model/BusinessServiceDTOList.java
M features/status/rest/src/main/java/org/opennms/web/rest/v2/status/model/NodeDTOList.java
M features/status/rest/src/main/java/org/opennms/web/rest/v2/status/model/StatusDTO.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/AbstractDaoRestServiceWithDTO.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/AlarmRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/ApplicationRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/ApplicationStatusRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/DiscoveryRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/EventRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/IfServiceRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/IpInterfaceRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/MenuRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/MinionRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/MonitoringLocationRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/MonitoringSystemsRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/NewsFeedRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/NodeCategoriesRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/NodeIpInterfacesRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/NodeMonitoredServiceRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/NodeRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/NodeSnmpInterfacesRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/NotificationRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/OutageRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/ProvisiondStatusRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/SituationsRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/SnmpInterfaceRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/SnmpMetadataRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/TopologyAssetDTO.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/TopologyAssetRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/TopologyViewDTO.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/TopologyViewRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/UserDefinedLinkRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/api/DataCollectionConfRestApi.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/api/EventConfRestApi.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/api/EventRestApi.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/api/NodeLinkRestApi.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/api/SnmpConfigRestApi.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/api/TrapdRestApi.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/infopanel/InfoPanelItem.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/infopanel/TopologyInfopanelRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/AddEventConfSourceRequest.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/AlarmMemoRequest.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/AlarmPropertyUpdateRequest.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/DataCollectionConfErrorResponse.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/DataCollectionConfUploadResponse.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/DataCollectionMibGroupPageResponse.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/DataCollectionResourceTypePageResponse.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/DataCollectionSystemDefPageResponse.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/EventConfErrorResponse.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/EventConfEventDeletePayload.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/EventConfEventEditRequest.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/EventConfEventPageResponse.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/EventConfSourceCreatedResponse.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/EventConfSourceDto.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/EventConfSourcePageResponse.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/EventConfUploadResponse.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/NodeServiceTypeDto.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/SnmpCollectionCreateSourceDto.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/SnmpCollectionSourceNamesAndIdsResponse.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/SnmpCollectionSourcePageResponse.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/SnmpConfigProfileDto.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/Snmpv3UserDto.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/SourceNameDto.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/TrapdConfigDto.java
Log Message:
-----------
NMS-20263: Document the v2 ReST API with request and response schemas and examples
Every one of the 356 v2 operations now carries a summary, a unique
operationId, a request schema and example where it reads a body, and a
schema and example per reachable status code. Each was exercised against a
running instance and the annotations describe what it did, including where
that differs from what the code appears to intend.
Operations with a summary go from 93 to 355, response contents with a schema
from 65 of 610 to 682 of 693, and response examples from none to 653.
Generator-assigned operationIds such as createSpecific_14 drop from 213 to 5.
Sixty-seven operations carried duplicate parameter declarations, which is
invalid OpenAPI; none do now.
The generic collection operations come from AbstractDaoRestServiceWithDTO,
which is generic, so a single annotation there would give every DAO-backed
resource the same operationId and no per-family entity schema. Each concrete
resource instead declares delegating overrides that call super and carry only
swagger annotations. No runtime logic changes.
Handlers that assemble an ad-hoc Map have no type to reference, so this adds
documentation-only classes describing those shapes. The bsm response DTOs
that carry a custom @JsonSerialize are documented by example alone: swagger-core
2.1.12 introspects such serializers through a Jackson method removed after
2.12, which aborts document generation.
Commit: fc815d8a791128a84b5a2640a456f48d664313d0
https://github.com/OpenNMS/opennms/commit/fc815d8a791128a84b5a2640a456f48d664313d0
Author: Marshall Massengill <[email protected]>
Date: 2026-08-26 (Wed, 26 Aug 2026)
Changed paths:
M features/measurements/api/src/main/java/org/opennms/netmgt/measurements/model/Expression.java
M features/measurements/api/src/main/java/org/opennms/netmgt/measurements/model/FilterDef.java
M features/measurements/api/src/main/java/org/opennms/netmgt/measurements/model/FilterMetaData.java
M features/measurements/api/src/main/java/org/opennms/netmgt/measurements/model/FilterParamDef.java
M features/measurements/api/src/main/java/org/opennms/netmgt/measurements/model/FilterParamMetaData.java
M features/measurements/api/src/main/java/org/opennms/netmgt/measurements/model/QueryMetadata.java
M features/measurements/api/src/main/java/org/opennms/netmgt/measurements/model/QueryNode.java
M features/measurements/api/src/main/java/org/opennms/netmgt/measurements/model/QueryRequest.java
M features/measurements/api/src/main/java/org/opennms/netmgt/measurements/model/QueryResource.java
M features/measurements/api/src/main/java/org/opennms/netmgt/measurements/model/QueryResponse.java
M features/measurements/api/src/main/java/org/opennms/netmgt/measurements/model/Source.java
M features/measurements/rest/src/main/java/org/opennms/web/rest/v1/MeasurementsRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/AcknowledgmentRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/AlarmRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/AlarmStatsRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/AssetRecordResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/AssetSuggestionsRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/AvailabilityRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/CategoryRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/ConfigRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/EventRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/FilesystemRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/ForeignSourceConfigRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/ForeignSourceRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/GraphRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/GroupRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/HardwareInventoryResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/HeatMapRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/IfServicesRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/InfoRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/KscRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/LogRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/MinionRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/MonitoringLocationsRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/NodeRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/NotificationRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/OnmsIpInterfaceResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/OnmsMonitoredServiceResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/OnmsSnmpInterfaceResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/OutageRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/RequisitionNamesRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/RequisitionRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/ResourceRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/ScheduledOutagesRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/SnmpConfigRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/TimelineRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/UserRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/WebAssetsRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/WhoamiRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/AgentConfigurationResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/DataCollectionConfigResource.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/DataCollectionLookupResponse.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/DataCollectionStatusResponse.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/DatetimeformatConfig.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/EmailNorthbounderConfigurationResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/JavamailConfigurationResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/JmxDataCollectionConfigResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/SnmpConfigurationResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/SnmpTrapNorthbounderConfigurationResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/SyslogNorthbounderConfigurationResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/TicketerConfig.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/TrapdConfigurationResource.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/model/AckOnlyForm.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/model/AcknowledgmentForm.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/model/AlarmAckForm.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/model/AvailabilityDataResponse.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/model/GroupUpdateForm.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/model/UserUpdateForm.java
A opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/model/WhoamiResponse.java
Log Message:
-----------
NMS-20263: Document the v1 ReST API with request and response schemas and examples
All 310 v1 operations now carry a summary, a unique operationId, and a schema
and example per reachable status code, each verified against a running
instance. Operations with a summary go from 32 to 310, response contents with
a schema from 273 of 494 to 606 of 606, and response examples from none to 516.
Where behaviour and intent disagree, the annotations record the behaviour: v1
error bodies are text/plain even under a JSON @Produces, form-encoded keys are
bean property names rather than the hyphenated names the read endpoints emit,
several fields are XML attributes and are dropped if sent as elements, dates
are epoch milliseconds in JSON and ISO-8601 in XML from the same field, and a
node may be addressed either by database id or by foreignSource:foreignId.
The /config family is documented for the first time; several of its resources
carried no annotations at all. Its writes re-marshal the whole target file,
which is noted on the tag because it discards comments in the shipped etc XML.
The /measurements component schemas named properties the API rejects: those
model classes carry Jackson 1 annotations and JAXB names that the generator
cannot see, and three @XmlValue properties were missing from the schema
entirely, leaving no way to express an expression or a filter parameter value.
A request assembled purely from the corrected schema now succeeds.
Compare: https://github.com/OpenNMS/opennms/compare/51129eb79e59%5E...fc815d8a7911
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