...
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:
Code Block | ||
---|---|---|
| ||
@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.
...