Page History

...

It's disabled by default. It's enabled by setting the tapestry.publish-openapi-description (SymbolConstants.PUBLISH_OPENAPI_DEFINITON) configuration symbol to true. If enabled, it will be available at the /openapi.json URL. This is configurable by using the tapestry.openapi-description-path (SymbolConstants.OPENAPI_DESCRIPTION_PATH) configuration symbol. 

All the entity classes returned by MappedEntityManager.getEntities() are automatically added to the schemas section of the generated description.  

Customizing names, summaries and descriptions using messages and configuration symbols

...

You can see which messages and symbols are being looked up by setting the debug level of the org.apache.tapestry5.internal.services.rest.DefaultOpenApiDescriptionGenerator class to DEBUG.

Customizing the consumed and produced MIME content types of an endpoint with @RestInfo

The @RestInfo annotation allows you to define, just for OpenAPI description generation purposes, what are the accepted MIME content types accepted by a REST endpoint event handler method, the produced types and what's the actual returned value type of the method when its execution succeeds. Many REST event handler methods usually have a return type of Object so it can return an HttpStatus instance of something goes wrong and a mapped entity class entity when the call is successful.

Here's one example: 

@RestInfo(produces = "text/plain", produces = "application/json", returnType = User.class)
Object onHttpGet(@RequestBody Long id) {
    User user = ...;
	if (!notFound) {
        return HttpStatus.notFound()
    }
    else {
        return user;    
    }
}

Further customizations

The generated description can be further customized by implementing the OpenApiDescriptionGenerator interface and contributing it to the OpenApiDescriptionGenerator service. The JSONObject generate(JSONObject documentation) method will receive the generated description and it can be changed by using the JSONObject methods. The return value should be the same object received as a parameter.

...