Parsing Javadoc comments to generate descriptions

[twobiers]

Hi,

I wonder if it makes sense to include the parsing of javadoc comments to create descriptions for schemas, paths, parameters, etc. in the standard.

The non-standard implementation micronaut-openapi does exactly that.

As a user, this would be a totally useful feature from my point of view.

[Azquelt]

This isn't something can be done by an implementation that scans classes at runtime (as OpenLiberty does) as the javadoc comments aren't available at runtime.

It also wouldn't work if you were using a third party jar unless it also includes the source code.

There's no reason that this functionality couldn't be provided by any implementation that operates at build time and has the source files available, but I wouldn't want it to be required by the spec.

[liefke]

I asked the same question at Stackoverflow: Generate OpenAPI descriptions from JavaDoc

I'm already serializing the JavaDoc during buildtime, so I guess I would need to implement my own OASFactoryResolver to offer the JavaDoc at runtime to the OpenAPI?

[MikeEdgar]

@liefke if you have made the comments available to your application at runtime in some format, you would probably want to use the OASModelReader to generate the initial OpenAPI model based on that data. In that case you may want to turn off annotation scanning with mp.openapi.scan.disable=true.

[liefke]

@MikeEdgar thanks for the clarification.

As you also are part of the SmallRye-Team, I hope that you can even answer my next answer, which is about integration into WildFly: As far as I understand the JavaDoc comment of OASModelReader (which needs to be visible to the application's classloader), I need to put my OASModelReader implementation into a WildFly-module? Or are the deployments scanned for such an implementation, like annotation scanning does, too?

[MikeEdgar]

@liefke you can place the OASModelReader implementation in your deployment/application (or a jar in the app's class path) and you'll need to include the mp.openapi.model.reader property with the fully-qualified class name of the reader.

[liefke]

@MikeEdgar Thank you, I got it running.

But if you read the original question of @tobi6112 you will notice, that we don't want to replace the OpenApi annotation parsing with our own implementation, but we only want to add the JavaDoc as description. So the OASFilter (property mp.openapi.filter in the file META-INF/microprofile-config.properties) is the much better solution.

Example:

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));
                }
            });
        }
    }
    ...
}

Side note: I could only override filterOpenAPI, because all other convenient filter methods do not provide the key of the corresponding map, e.g. filterSchema(Schema) doesn't include the name of the schema.