Skip to main content

Swagger Models

Outdated examples (10.0)

Examples on this page using @HookEvent(INIT) or RestContext.Builder is pre-10.0 and kept only for historical context. Configure schema generation through @Bean(name="jsonSchemaGenerator") with a fully built JsonSchemaGenerator. See the V10 Migration Guide.

The JsonSchemaGenerator.Builder.useBeanDefs() setting can be used to reduce the size of your generated Swagger JSON files by creating model definitions for beans and referencing those definitions through $ref attributes.

This setting is disabled by default but can be set by supplying a jsonSchemaGenerator bean:

import org.apache.juneau.commons.inject.Bean;

@Bean(name="jsonSchemaGenerator")
public static JsonSchemaGenerator jsonSchemaGenerator(JsonSchemaGenerator.Builder b) {
    return b.useBeanDefs().build();
}

In the Swagger UI, this causes bean definitions to show up in the Models section at the bottom of the page:

Models section​

Models section

Models section with Order bean expanded​

Models section with Order bean expanded

In the generated Swagger JSON, embedded schema information for beans will be replaced with references such as the one shown below for the Order bean:

{
    "swagger": "2.0",
    "paths": {
        "/store/order": {
            "get": {
                "operationId": "getOrders",
                "summary": "Petstore orders",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "description": "java.util.Collection",
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/Order"
                            }
                        },
                        ...
                    ...
                ...
            ...
        ...
    },
    "definitions": {
        "Order": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "integer",
                    "format": "int64"
                },
                "petId": {
                    "type": "integer",
                    "format": "int64"
                },
                "shipDate": {
                    "type": "string"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "PLACED",
                        "APPROVED",
                        "DELIVERED"
                    ]
                }
            },
            "description": "org.apache.juneau.petstore.dto.Order",
            "example": {
                "id": 123,
                "petId": 456,
                "shipDate": "2012-12-21",
                "status": "APPROVED"
            }
        },
    ...
}

Note that this does not affect how the information is rendered for that bean in the Swagger UI:

Order bean rendered in Swagger UI