Quick notes for generating the docs for comparison

cd services && mvn -s ../maven-settings.xml -Pjboss-release clean package

Docs should be generated at services/target/apidocs-rest/output/index.html

And then can be compared with last release API docs at https://www.keycloak.org/docs-api/21.1.1/rest-api/index.html

Being part of the team that builds the UIs that consume these APIs this would be a huge help to us. It would essentially remove the need for us to maintain a separate Admin Client (JS), as we could use the schema as a means of generating the client itself.

Curious where this will lead.

See also #10775, #12133, #12313 and #19132 for historical discussion on this feature.

@jonkoops @jsorah I just wonder if now that we are on Quarkus it would be better to benefit from quarkus-smallrye-openapi and quarkus-swagger-ui so that we would be able to document our endpoints like:

@GET
@Path("/some/endpoint")
@Operation(summary = "Returns a greeting message")
public String something() {
    return "something";
}

More details: https://quarkus.io/guides/openapi-swaggerui

@jonkoops @jsorah I just wonder if now that we are on Quarkus it would be better to benefit from quarkus-smallrye-openapi and quarkus-swagger-ui so that we would be able to document our endpoints like:

@GET
@Path("/some/endpoint")
@Operation(summary = "Returns a greeting message")
public String something() {
    return "something";
}

More details: https://quarkus.io/guides/openapi-swaggerui

That's a good question - I initially was scoping to just offline generation for the documentation and trying to keep the changes a little conservative (though they still involve annotations in all the resource classes). I am not sure if the offline generation would still be possible with the quarkus based annotations, but its something I can look into trying and dropping the other openapi dependency.

I'm a little cautious about inclusion of the Swagger UI - it has had a few XSS vulnerabilities in the past, so at a minimum probably both swagger-ui and openapi spec availability should be controlled via configuration somehow.

@abstractj @jonkoops I've updated the branch to use the eclipse microprofile / smallrye-openapi variant of the annotations. The PR is already rather large considering the number of classes that needed to be annotated - I am thinking if we are OK with this approach I can make a separate PR that exposes the actual swagger-ui and openapi spec through the quarkus dist as "opt-in" properties. I have most of that work done locally already.

One issue I ran into had to do with the generic handling of OPTIONS / preflight requests to the admin resources and how that required an "Object" return type on the Realm Admin Resource, which resulted in the annotation scanning to fail finding the relevant classes. I was able to get around the typing issue using a subclass, though this is less than ideal -> https://github.com/keycloak/keycloak/pull/20669/files#diff-c1ffdb124c9481c03397c671cf35661db45cb91019da2a180f4fcaebe92d5b9d

I'm also not sure who else I should pull into this conversation / PR for feedback.

Focus for this PR should be on fixing the offline API documentation.

Considering online API documentation is something we can consider later, but there needs to be some reasoning for considering online API docs exposed by the Keycloak Server. Examples of this could be ability to try the API through the browser (would require figuring out how to authenticate though), or if we have dynamic APIs (that's a bigger effort, but in general APIs could get metadata on how the server is configured, what custom providers there are, etc. to generate a bespoke API for a given server/realm). We'd also need an option to enable/disable this, including removing things from the runtime when it's disabled.

@rmartinc Yes, removing javadoc can be also an option. I am not sure how much people rely on the javadoc for example during coding. I am personally not much and since things would be documented in the code with openapi annotations, it is possibly fine? But no need to change anything in this PR (Just though for the future...)

@rmartinc @mposolda - Thanks for the reviews - I've updated the dependency management bits as suggested. I was also not sure what to do about the Javadoc since now its basically duplicated but it may have been used by folks too. I'll have to look at what the store team has done and see if theres an approach we can go with as a followup.

I think @jonkoops your team is now tagged for review too because I did modify the rest/admin-ui-ext/pom.xml to take advantage of the dependency management in the top-level pom.xml - there is net-no change for that module as it is using the same versions as before.

Thanks for landing this!

Thank you all for including this, it is amazing to see this happening. Thank you @jsorah.

Just to understand, this means we have an OpenAPI endpoint in latest versions of Keycloak ?
Or the endpoint to access the OpenPAPI documentation is not available yet ?

If it is available, what is the endpoint ? I cannot find any documentation on this.

Just to understand, this means we have an OpenAPI endpoint in latest versions of Keycloak ? Or the endpoint to access the OpenPAPI documentation is not available yet ?

If it is available, what is the endpoint ? I cannot find any documentation on this.

Instead of using Javadoc to generate the REST Admin API documentation it was switched over to OpenAPI annotations to get something similar, because the previous plugin to do so had various incompatibility issues.

There isn't an OpenAPI spec published as part of this change except as an intermediate artifact in generating the documentation. I believe there is an open PR to add this generated spec to the documentation, but I think it probably needs some more work before someone generates actual clients from the spec.