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

**URL:** <https://forum.keycloak.org/t/how-to-document-custom-apis-in-a-keycloak-extension-using-swagger-openapi/29031>\
**Category:** Getting advice\
**Tags:** documentation\
**Created:** [December 2, 2024, 4:18pm UTC](https://forum.keycloak.org/t/how-to-document-custom-apis-in-a-keycloak-extension-using-swagger-openapi/29031 "2024-12-02T16:18:10Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![amir\_ka](https://yyz2.discourse-cdn.com/free1/user_avatar/forum.keycloak.org/amir_ka/32/11721_2.png) [@amir\_ka](https://forum.keycloak.org/u/amir_ka)\
**Post date:** [December 2, 2024, 4:18pm UTC](https://forum.keycloak.org/t/how-to-document-custom-apis-in-a-keycloak-extension-using-swagger-openapi/29031/1 "2024-12-02T16:18:10Z")

</div>

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.