V1 Configuration - SMILEY4/ktor-openapi-tools GitHub Wiki

When installing the plugin with install(SwaggerUI), sensible default values will be used and can be overwritten when required.

By default, the swagger-ui is available at "localhost:8080/swagger-ui" (assuming the application is running on localhost:8080).

Swagger

Configuration of the Swagger-UI itself

install(SwaggerUI) {
    swagger {
        forwardRoot = false
        swaggerUrl = "swagger-ui"
        authentication = "MySwaggerAuth"
        onlineSpecValidator()
        displayOperationId = true
        showTagFilterInput = true
        sort = SwaggerUiSort.HTTP_METHOD
        syntaxHighlight = SwaggerUiSyntaxHighlight.MONOKAI
    }
    //...
}

• forwardRoot - whether to forward the "/"-route to the swagger-ui
• swaggerUrl - the url at which the swagger-ui is available
• authentication - the name of the authentication method to use for the Swagger-UI and OpenApi-Spec
• validatorUrl - Swagger UI can validate specs against an online validator. This option can be used to enable/disable the validation or supply an url to a custom validator. disableSpecValidator() to disable validation (=default), specValidator("myUrl") to point to a custom validator, onlineSpecValidator() to use the default swagger-ui validator (https://validator.swagger.io/validator)
• displayOperationId - Whether to show the operation-id of endpoints in the list
• showTagFilterInput - Whether the top bar will show an edit box that you can use to filter the tagged operations.
• sort - Apply a sort to the operation list of each API
• syntaxHighlight - Syntax coloring theme to use

Info

Metadata about the API. See the official OpenAPI Specification for further information.

install(SwaggerUI) {
    info {
        title = "Api"
        version = "latest"
        description = "My Api"
        termsOfService = "http://example.com/terms"
        contact {
            name = "API Support"
            url = "http://www.example.com/support"
            email = "[email protected]"
        }
        license {
            name = "Apache 2.0"
            url = "https://www.apache.org/licenses/LICENSE-2.0.html"
        }
    }
    //...
}

Server

Connectivity information to any amount of target servers. See the official OpenAPI Specification for further information.

install(SwaggerUI) {
    server {
        url = "localhost:8080"
        description = "Development server"
    }
    server {
        url = "https://example.com/"
        description = "Example server"
    }
    //...
}

Security Scheme

The security mechanisms that can be used across the API. See the official OpenAPI Specification for further information.

install(SwaggerUI) {
    securityScheme("MyBasicAuth") {
        type = AuthType.HTTP
        scheme = AuthScheme.BASIC
    }
    securityScheme("MyJwtAuth") {
        type = AuthType.HTTP
        scheme = AuthScheme.BEARER
        bearerFormat = "jwt"
    }
    //...
}

Tags

Metadata for tags.

install(SwaggerUI) {
    tag("MyTag1") {
        description = "My first tag"
        externalDocDescription = "Description of additional external documentation"
        externalDocUrl = "https://example.com/"
    }
    tag("MyTag2") {
        description = "My second tag"
        externalDocDescription = "Description of additional external documentation"
        externalDocUrl = "https://example.com/"
    }
    //...
}

• tag - adds metadata to the tag with the given name
• description - a short description of the tag
• externalDocDescription - a short description of the additional external documentation
• externalDocUrl - the url to an additional external documentation

Schemas

Provide custom schemas or a custom schema-builder.

install(SwaggerUI) {
	schemas {
		//...
	}
	//...
}

See Response Bodies for more information.

Others

Miscellaneous configuration

install(SwaggerUI) {
    defaultUnauthorizedResponse = {
        description = "Username or password invalid."
        // ...
    }
    defaultSecuritySchemeName = "MyBasicAuth"
    defaultSecuritySchemeNames = setOf("MyBasicAuth", "MyTokenAuth")
    automaticTagGenerator = { url -> url.firstOrNull() }
    schemasInComponentSection = true
    examplesInComponentSection = true
    pathFilter = { method, url => url.firstOrNul() != "hidden" }
    schemaGeneratorConfigBuilder.with(Option.GETTER_METHODS)
    canonicalNameObjectRefs = false
    ignoredRouteSelectors = listOf(MyIgnoredRouteSelector::class)
    //...
}

• defaultUnauthorizedResponse - the response-information for a "401 Unauthorized"-response to automatically add to each protected route - if not specified otherwise. See Responses for more information.
• defaultSecuritySchemeName - The name of the security scheme to automatically use for each protected route - if not specified otherwise.
• defaultSecuritySchemeNames - The name of the security schemes to automatically use for each protected route - if not specified otherwise.
• automaticTagGenerator - Takes the url of a route as a list (split at "/") and returns an OpenAPI-Tag or null for the route (null for "no tag").
• schemasInComponentSection - Whether to put json-schemas (of request,response bodies) into the "components"-section
• examplesInComponentSection - Whether to put examples (of request,response bodies) into the "components"-section
• pathFilter - Filter to apply to all routes. Return 'false' for routes to not include them in the OpenApi-Spec and Swagger-UI.
• schemaGeneratorConfigBuilder - can be used to customize or replace the configuration-builder for the json-schema-generator (see https://victools.github.io/jsonschema-generator/#generator-options for more information)
• canonicalNameObjectRefs - false (default) to use the shorter simple-name of a class for an object reference or true to use the full canonical name (class + package-name)
• ignoredRouteSelectors - ktor route-selectors (and all their sub-classes) in this list are ignored in the route-urls