SwaggerService

Generates Swagger schema definition files to describe the public and/or private RESTful APIs exposed by the RestfulObjects viewer.

These spec files can then be used with the Swagger UI page to explore the REST API, or used to generate client-side stubs using the Swagger codegen tool, eg for use in a custom REST client app.

API

SwaggerService.java
interface SwaggerService {
  String generateSwaggerSpec(Visibility visibility, Format format)     (1)
}
1 generateSwaggerSpec(Visibility, Format)

Generate a Swagger spec with the specified visibility and format.

Members

generateSwaggerSpec(Visibility, Format)

Generate a Swagger spec with the specified visibility and format.

Implementation

The framework provides a default implementation of the service, o.a.c.viewer.restfulobjects.rendering.service.swagger.SwaggerServiceDefault.

Usage Notes

Not all of the REST API exposed by the REST API (Restful Objects viewer) is included in the Swagger schema definition files; the emphasis is those REST resources that are used to develop custom apps: domain objects, domain object collections and action invocations.

When combined with Apache Causeway' own simplified representations, these are pretty much all that is needed for this use case.

The service is_not_ (currently) used by the framework itself; it is provided as a convenience for developers to build REST applications.

See also

  • SwaggerServiceMenu

    part of the REST API (Restful Objects viewer), this provides a prototype action that enables the swagger spec to be downloaded from theUI.

  • SwaggerExporter

    can be used to generate a Swagger spec, for example within a test suite or larger build pipeline.

    An example of its use can be found in the reference app:

    SwaggerExport_IntegTest.java
    @Import({
        CausewayModuleViewerRestfulObjectsJaxrsResteasy4.class
})
class SwaggerExport_IntegTest extends ApplicationIntegTestAbstract {

    @Inject ServiceRegistry serviceRegistry;

    @Test
    void export() throws IOException {
        val swaggerExporter = new SwaggerExporter(serviceRegistry);
        swaggerExporter.export(Visibility.PRIVATE, Format.JSON);
    }
}