Notes on how to document the new Account REST API

[abstractj]

Even though it's clear that we should have everything under the REST API guidelines, I would like to remove the clutter and add the notes of my findings around the REST API documentation. So we can agree on what to do next, update the content of this document and eventually merge it with REST API guidelines.

@stianst please let me know what is missing for you or should change. The content is pretty straightforward.

[stianst]

I don't understand this comment. Do you mean if they are not generated, but rather some how hand crafted?

[abstractj]

@stianst I can do some updates in this paragraph. But in summary, I'd like to split the work into 2 steps if we agree:

1. Dynamic documentation.

That's the most important thing at the moment from my point of view. And that means that changes into the code should immediately be reflected in the OpenAPI document.

2. Static documentation

Important, but we will only generate it at each release. That means that changes between releases won't be reflected immediately and in theory, could get out of date. That's what I meant, but of course, it's not the end of the world.

The reason why I see 1 as something more important, it's because it requires changes on Keycloak that depends on WildFly and requires more testing. And also I didn't want to introduce too many changes in one go.

[stianst]

Is there a Maven plugin available that can generate the OpenAPI document without starting the server?

[EricWittmann]

Not to my knowledge. But I think there is an opportunity here to collaborate with the SmallRye OpenAPI project (Red Hat's implementation of the Microprofile-OpenAPI spec) to create one. I believe it would be quite easy to integrate SmallRye OpenAPI into a maven plugin to generate the OpenAPI at build time rather than runtime. Some of the Microprofile Specification features assume things are happening at runtime (e.g. filtering, model reader, etc) but the most important part (generating an OpenAPI document from annotated JAX-RS code) can be done at build time. All we need in the SmallRye OpenAPI impl is a ShrinkWrap Archive with the compiled, annotated JAX-RS classes (and java beans). So I think a maven plugin would be fairly trivial to write.

[abstractj]

Not that I know. Maybe what Eric suggested is something to consider in the future or discuss with Quarkus team.

[stianst]

Is there a decent Maven plugin available that can generate HTML documentation from the OpenAPI document? It does seem like this would be incredibly useful as I doubt everyone will want to download Swagger and generate the docs themselves.

[EricWittmann]

Yes: https://openapi-generator.tech/docs/plugins/

For ReDoc I don't think there is a maven plugin, but it's an NPM based tool - so using one of the node maven plugins (e.g. frontend-maven-plugin) is an easy option.

[abstractj]

@stianst it is not necessary to download Swagger. Once we have the OpenAPI document people can use any tool to view the documentation. Of course, from the usability standpoint is not ideal, but I think that generate the OpenAPI document should be our priority.

@EricWittmann thank you, I will give that a try.

[EricWittmann]

+1 to the idea that the generation of the OpenAPI doc being the priority. Everything else flows well once that document exists. The trick is how/when to generate that document.

[stianst]

Should it not rather be '/auth/openapi/account'? We'll want to have separate OpenAPI documents for different APIs, and eventually we will want this for the admin endpoints (and others) as well.

What about versioning? Would it be '/auth/openapi/account' for the latest, and then you can also grab for a previous version using '/auth/openapi/account/'?

[EricWittmann]

Note that Microprofile OpenAPI does not support multiple separate APIs. The specification dictates that a single OpenAPI file be accessible at the /openapi endpoint (in the case of Wildfly it would be /context/openapi I assume, although I haven't looked at how Wildfly handles this). Like all Microprofile specs, the MP-OpenAPI spec was meant to be used in single-application platforms. So if you have multiple separate APIs in the same application context, and you want to document them as separate OpenAPI files, the Microprofile-OpenAPI spec will not let you do that.

That said, I do think using the MP-OpenAPI annotations as described above is the right thing to do. It just might be the case that you will need to figure out how to leverage them in a non-standard way).

[abstractj]

Agree with Eric here. What I had in mind thinking about admin vs account endpoints make use of tags. For example:

@Tag(name="Account REST API", description="Account REST API operations."),
@Tag(name="Admin REST API", description="Admin REST API operations."),

I can do some updates into the document to cover these scenarios.

[EricWittmann]

This is a very popular tool and a reasonable thing to use, certainly. However in my opinion the user interface is ... not great. Before making a decision on this, take a look at ReDoc as an alternative. We use that in Apicurio Studio to visualize the API design. An example: https://studio-ws.apicur.io/sharing/76f236d3-1312-4548-a4d1-400487188c66

Functionally they are very similar, I just think the user experience for ReDoc is much better. The main difference between the two (functionally) is that Swagger UI is interactive - when configured properly it will allow users to not only view documentation but also make test API calls. Useful when your Keycloak server is running and accessible, but not when publishing API docs to a project site.

[EricWittmann]

I would actually recommend this instead: https://github.com/OpenAPITools/openapi-generator

Although again, I think ReDoc is a better experience for users consuming the documentation, but that's a matter of preference (ReDoc has its own CLI for generating static/publishable HTML).

[abstractj]

Thanks Eric, I will look into that and update the document.

[abstractj]

@stianst updated with Eric's suggestion. Indeed ReDoc should be the way to go.