How to document custom APIs in a Keycloak extension using Swagger/OpenAPI?

Getting advice
1

Hi,
I’m developing a custom Keycloak extension and want to expose custom APIs as part of Keycloak’s endpoints (e.g., /admin/realms/<realm>/custom). Additionally, I want to document these APIs using Swagger/OpenAPI and serve the Swagger UI for them, similar to how Keycloak’s admin API is documented.

I followed these steps:

  1. Created a JAX-RS resource for the custom API.
  2. Registered the resource using a RealmResourceProvider and RealmResourceProviderFactory.
  3. Added the SmallRye OpenAPI and Swagger UI dependencies to the extension’s pom.xml.
  4. Tried adding Quarkus OpenAPI-related properties (e.g., quarkus.swagger-ui.always-include=true) in a new application.properties file inside the extension.

However, the APIs work but the Swagger/OpenAPI documentation does not show up. The application.properties is not recognized, and Swagger UI is not accessible at /swagger-ui or /openapi.

  1. Ensured that the extension was correctly deployed and the custom API worked at http://localhost:8080/admin/realms/master/custom.
  2. Verified dependencies for quarkus-smallrye-openapi and quarkus-swagger-ui in the pom.xml.

Despite these efforts, Swagger UI and OpenAPI documentation are not generated or accessible.