You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@nifi.apache.org by "mosermw (via GitHub)" <gi...@apache.org> on 2026/03/03 19:53:13 UTC
[PR] NIFI-15662 correct some swagger annotations for REST API [nifi]
mosermw opened a new pull request, #10957:
URL: https://github.com/apache/nifi/pull/10957
# Summary
[NIFI-15662](https://issues.apache.org/jira/browse/NIFI-15662)
Correct some Swagger annotations for nifi-api documentation
- corrected some Parameter descriptions
- added some missing Parameter descriptions
- removed a "description" where it was the same as the "summary" in ParameterContextResource
- various typos and static code analysis warnings
- moved ProcessGroupResource Jersey FormDataParam annotations to JAX-RS FormParam annotations (though the descriptions do not appear in the Swagger documentation for either, and I don't know why)
# Tracking
Please complete the following tracking steps prior to pull request creation.
### Issue Tracking
- [x] [Apache NiFi Jira](https://issues.apache.org/jira/browse/NIFI) issue created
### Pull Request Tracking
- [x] Pull Request title starts with Apache NiFi Jira issue number, such as `NIFI-00000`
- [x] Pull Request commit message starts with Apache NiFi Jira issue number, as such `NIFI-00000`
- [x] Pull request contains [commits signed](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) with a registered key indicating `Verified` status
### Pull Request Formatting
- [x] Pull Request based on current revision of the `main` branch
- [x] Pull Request refers to a feature branch with one commit containing changes
# Verification
Please indicate the verification steps performed prior to pull request creation.
### Build
- [x] Build completed using `./mvnw clean install -P contrib-check`
- [x] JDK 21
- [ ] JDK 25
### Licensing
- [ ] New dependencies are compatible with the [Apache License 2.0](https://apache.org/licenses/LICENSE-2.0) according to the [License Policy](https://www.apache.org/legal/resolved.html)
- [ ] New dependencies are documented in applicable `LICENSE` and `NOTICE` files
### Documentation
- [x] Documentation formatting appears as expected in rendered files
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@nifi.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] NIFI-15662 correct some swagger annotations for REST API [nifi]
Posted by "Chaffelson (via GitHub)" <gi...@apache.org>.
Chaffelson commented on PR #10957:
URL: https://github.com/apache/nifi/pull/10957#issuecomment-4007888506
Thanks @mosermw for your consideration of the feedback and the admittedly minor change.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@nifi.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] NIFI-15662 correct some swagger annotations for REST API [nifi]
Posted by "Chaffelson (via GitHub)" <gi...@apache.org>.
Chaffelson commented on PR #10957:
URL: https://github.com/apache/nifi/pull/10957#issuecomment-3999778093
## nipyapi Client SDK Impact Assessment
I maintain nipyapi (https://github.com/Chaffelson/nipyapi), a Python client SDK generated from NiFi's swagger spec. I've built nifi-web-api from this PR branch and regenerated the client to assess impact.
### Summary
The annotation changes produce two breaking changes to the generated client method signatures:
- search_flow() - q parameter now required (was optional)
- import_process_group() - body parameter now required and moved to first position
### Details
FlowResource.searchFlow - The new @Parameter annotations on q and a query params cause q to become a required positional argument in the generated client. Previously callers could omit it.
ProcessGroupResource.importProcessGroup - The new @Parameter(description=..., required=true) on the body causes it to become required and reordered to first position.
### Assessment
These changes are arguably correct - you can't meaningfully search without a query term, and you can't import without a body. But they will break existing SDK callers who relied on the previous optional behavior.
The @FormDataParam to @FormParam migration doesn't affect the swagger spec output (both produce type: object for the file parameter), so that's fine from a client generation perspective.
### Recommendation
No changes requested - the breaking changes reflect correct API semantics. Just flagging for awareness that downstream SDK users may need to update their code.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@nifi.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] NIFI-15662 correct some swagger annotations for REST API [nifi]
Posted by "exceptionfactory (via GitHub)" <gi...@apache.org>.
exceptionfactory merged PR #10957:
URL: https://github.com/apache/nifi/pull/10957
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@nifi.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] NIFI-15662 correct some swagger annotations for REST API [nifi]
Posted by "mosermw (via GitHub)" <gi...@apache.org>.
mosermw commented on PR #10957:
URL: https://github.com/apache/nifi/pull/10957#issuecomment-4000188317
Great assessment @Chaffelson, thank you for doing this. I would be happy to amend this PR to remove "required = true" in these two places. I did add it where the API would return meaningless results without the presence of the parameter.
I did test /nifi-api/flow/search-results without a "q" parameter and NiFi returned a valid response with no search results, so in that sense the "q" parameter is not really required.
I also added "required = true" to the "file" FormParam of ProcessGroupResource.uploadProcessGroup. I suspect the Jersey FormDataParam parameters without a DefaultValue are considered required by default, so it didn't appear in your analysis.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@nifi.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org