V2 Request and Response Bodies Custom Schemas - SMILEY4/ktor-openapi-tools GitHub Wiki

Schemas can be pre-configured in the plugin-configuration and then referenced later by bodies as their type.

By default, custom schemas are only included in the generated spec when they are directly references by at least one documentation of a route. The behavor can be changed with the customSchemas.includeAll-field in the plugin-config.

Custom schemas are defined in the schemas-section of the plugin config. Schemas can either be defined as a string, an instance of "Schema" or as a remote-schema via an url.

Each schema defined that way must have an unique id used to reference it later.

install(SwaggerUI) {
	schemas {
    	json("myCustomJsonSchema") {
        	"""
            {
                "type": "object",
                "properties": { ... }
            }
        	""".trimIndent()
        }
        openApi("myCustomSchema") {
            Schema<Any>().apply { /*...*/ }
        }
        remote("myRemoteSchema", "http://localhost:8080/schemas/myschema.json")
    }
}

• json("schemaId") - provide a custom schema as a json-schema-string. The schema should not contain any subschemas, but can reference other schemas in the components section with "$ref": "#/components/schemas/yourschemaname".
• openApi("schemaId") - provide the schema as a swagger "Schema"-Object
• remove("schemaId") - the schema can be found at the given url. Only the reference is added to the final OpenApi-Spec, not the complete schema.

Custom schemas can be referenced by their id as the body of an request or response (or part of a multipart-body). No additional type needs to be provided.

request {
	body("myCustomJsonSchema") {
		//...
	}
}

By default, the schema is used as an object as is, but can also be references as the element-type of an array

body(custom"myCustomJsonSchema")) // "myCustomJsonSchema" is the schema of the body
body("myRemoteSchema") // same as "custom("myRemoteSchema")"

body(multipleOf(custom("myCustomSchema"))) // body is an array with elements of in the schema "myCustomSchema"