[RLM] Add missing OpenAPI annotations to API methods #44672
Conversation
sguilhen
left a comment
There was a problem hiding this comment.
Thanks for the PR, @MOUNIAT-1002 . In general it looks good, just need to address a few points.
| import org.eclipse.microprofile.openapi.annotations.tags.Tag; | ||
| import org.keycloak.services.resources.KeycloakOpenAPI; | ||
|
|
||
| public class WorkflowResource { |
There was a problem hiding this comment.
The resource classes are missing the @Extension annotation:
@Extension(name = KeycloakOpenAPI.Profiles.ADMIN, value = "")
| } | ||
|
|
||
| @DELETE | ||
| @Tag(name = KeycloakOpenAPI.Admin.Tags.REALMS_ADMIN) |
There was a problem hiding this comment.
For workflows we probably want to add a new WORKFLOWS tag, and use it in all endpoint methods instead of REALM_ADMIN
|
|
||
| @GET | ||
| @Produces({YAMLMediaTypes.APPLICATION_JACKSON_YAML, MediaType.APPLICATION_JSON}) | ||
| @Produces({MediaType.APPLICATION_JSON, YAMLMediaTypes.APPLICATION_JACKSON_YAML}) |
There was a problem hiding this comment.
Could you please revert this particular change? For workflows application/yaml will be the preferred choice of format, and if a HTTP request contains both JSON and YAML in the Accepts header, the order in the @Produces annotation will define the format that will be returned (instead of the order found in the Accepts header). So we had to put YAML first to give YAML priority in case the request contains both.
| import org.eclipse.microprofile.openapi.annotations.tags.Tag; | ||
| import org.keycloak.services.resources.KeycloakOpenAPI; | ||
|
|
||
| public class WorkflowsResource { |
There was a problem hiding this comment.
Same thing - we need the @Extension annotation at the class level.
|
|
||
| @POST | ||
| @Consumes({MediaType.APPLICATION_JSON, YAMLMediaTypes.APPLICATION_JACKSON_YAML}) | ||
| @Tag(name = KeycloakOpenAPI.Admin.Tags.REALMS_ADMIN) |
There was a problem hiding this comment.
Same comment about the tag - we need a WORKFLOWS tag for these endpoints.
Add missing OpenAPI annotations to API methods across the REST services so the generated OpenAPI spec and Swagger UI include the complete API metadata. Ensures consistent tagging and parameter/response descriptions for admin endpoints. No behavior change; only adds documentation annotations. Closes keycloak#42695 Signed-off-by: MOUNIAT-1002 <[email protected]>
e19f927 to
313a4f6
Compare
|
Hello @sguilhen, I just fixed the code. Tell me if everything is okay. Thank you, |
|
Thanks @MOUNIAT-1002 - would you be able to resolve the conflicts for this one? Then we can trigger the CI and get it merged |
|
@MOUNIAT-1002 - since I can't push changes to your branch I've fetched your commit and added another one with some missing pieces. I've opened #45007 as a replacement for this PR. Your contribution will be added as part of that other PR (left your original commit unchanged). |
Add missing OpenAPI annotations to workflow admin API
This PR adds the missing OpenAPI annotations to the workflow-related Admin REST endpoints.
By completing these annotations, the generated OpenAPI specification and Swagger UI now include accurate metadata for all workflow operations.
Changes
Added @tag, @operation, and @parameter annotations to:
WorkflowResource
WorkflowsResource
Standardized the ordering of @produces values to follow Keycloak conventions (application/json first).
Added missing @consumes(MediaType.APPLICATION_JSON) where required.
Improved description fields so the workflow activation, deactivation, and retrieval endpoints are fully documented.
Ensured consistency with existing Admin REST API documentation style.
Notes
This PR introduces no functional or behavioral changes.
It affects documentation only and is limited to OpenAPI metadata.
These updates enhance the clarity and completeness of the Admin REST API documentation for workflow features, especially as they mature in upcoming milestones.
Closes #42695