Skip to main content

Swagger Models

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 on the RestContext.Builder object:

@HookEvent(INIT)
public void init(RestContext.Builder builder) {
    builder.jsonSchemaGenerator().useBeanDefs();
}

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.examples.rest.petstore.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