Generate OpenAPI descriptions from JavaDoc

Question

I have an application which provides an API with JAX-RS (Java API for RESTful Web Services / JSR-311).

For documentation purposes I provide an URL according to the OpenAPI-Specification, which is generated by Eclipse MicroProfile OpenAPI.

Everything is working fine, except the descriptions of the methods and parameters, which I need to add twice - in annotations and in JavaDoc:

/**
 * Finds all resources with the given prefix.
 *
 * @param prefix
 *            the prefix of the resource
 * @return the resources that start with the prefix
 */
@GET
@Path("/find/{prefix}")
@Produces(MediaType.APPLICATION_JSON)
@Operation(description = "Finds all resources with the given prefix")
public List<Resource> find(
        @Parameter(description = "The prefix of the resource") 
        @PathParam("prefix") final String prefix) {
    ...
}

I know that no runtime library can read the JavaDoc (because it is not part of the class files), which is the main reason for the annotations. But I wonder if there is some other option for one of the OpenAPI generation tools (Swagger, Eclipse MicroProfile OpenAPI, ...), which prevents me from manually syncing the documentation?

In another project for example I'm using a doclet which serializes the JavaDoc and stores it in the class path, to present an Beans API documentation to the user at runtime. But even if I make use of this doclet here, I see no option to provide that JavaDoc descriptions to the OpenAPI libraries during runtime.

I know that I could drop the JavaDoc, if the users of my API use only "foreign languages", as they wouldn't see the JavaDoc anyway. But what happens if the other side of the API is a JAX-RS client? In that case the JavaDoc would be a huge support.

Unfortunately not. I think I will write some build tool, which enhances the classes automatically, as soon as I really need this. — Tobias Liefke, May 07 '21 at 16:41
For what it's worth, annotation processors can [read Javadoc comments at compile time and make them available at runtime](https://stackoverflow.com/a/45887347/611819). — dnault, Sep 25 '21 at 18:17
@dnault The question was not how to serialize the JavaDocs at compile time - a doclet is enough to do this, no need for annotation processors. The question is how to offer the JavaDoc during runtime to the OpenAPI generation tools. — Tobias Liefke, Sep 26 '21 at 20:48

score 3 · Accepted Answer · answered Mar 23 '22 at 20:45

I got it running with Eclipse Microprofile OpenAPI.

I had to define my own OASFilter:

public class JavadocOASDescriptionFilter implements OASFilter {

    @Override
    public void filterOpenAPI(final OpenAPI openAPI) {
        openAPI.getComponents().getSchemas().forEach(this::initializeSchema);
        openAPI.getPaths().forEach(this::initializePathItem);
    }

    private void initializeSchema(final String name, final Schema schema) {
        final SerializedJavadoc javadoc = findJavadocForSchema(name);
        if (StringUtils.isEmpty(schema.getDescription())) {
            schema.setDescription(javadoc.getTypeComment());
        }
        if (schema.getProperties() != null) {
            schema.getProperties().forEach((property, propertySchema) -> {
                if (StringUtils.isEmpty(propertySchema.getDescription())) {
                    propertySchema.setDescription(javadoc.getAttributeComments().get(property));
                }
            });
        }
    }
    ...
}

Then I had to declare that filter in META-INF/microprofile-config.properties:

mp.openapi.filter=mypackage.JavadocOASDescriptionReader

See here for the discussion on this topic: https://github.com/eclipse/microprofile-open-api/issues/485

Generate OpenAPI descriptions from JavaDoc

1 Answers1