OpenApi Spec Configuration

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

More information can be found here: https://swagger.io/specification/

install(SwaggerUI) {
    info {
        title = "Example API"
        version = "latest"
        summary = "An example api."
        description = "This i an example api."
        termsOfService = "example.com"
        contact {
            name = "Mr. Example"
            url = "example.com"
            email = "[email protected]"
        }
        license {
            name = "Example License"
            url = "example.com"
            identifier = "Apache-2.0"
        }
    }
    externalDocs {
        url = "example.com"
        description = "Project documentation"
    }
    server {
        url = "localhost"
        description = "local dev-server"
        variable("version") {
            default = "1.0"
            enum = setOf("1.0", "2.0", "3.0")
            description = "the version of the server api"
        }
    }
    security {
        defaultUnauthorizedResponse {
            description = "Username or password is invalid"
        }
        defaultSecuritySchemeNames = setOf("MySecurityScheme")
        securityScheme("MySecurityScheme") {
            type = AuthType.HTTP
            scheme = AuthScheme.BASIC
        }
    }
    tags {
        tagGenerator = { url -> listOf(url.firstOrNull()) }
        tag("users") {
            description = "routes to manage users"
            externalDocUrl = "example.com/wiki/users"
            externalDocDescription = "Users documentation"
        }
    }
    outputFormat = OutputFormat.JSON
}

Property	Description	Default
info	OpenAPI info configuration - provides metadata about the API.
info.title	The title of the api.	"API"
info.version	The version of the OpenAPI document.	"latest"
info.description	A short description of the API.	null
info.summary	A short summary of the API.	null
info.termsOfService	A URL to the Terms of Service for the API. MUST be in the format of a URL.	null
info.contact	The contact information for the exposed API.
info.contact.name	The identifying name of the contact person/organization.	null
info.contact.url	The URL pointing to the contact information. MUST be in the format of a URL.	null
info.contact.email	The email address of the contact person/organization. MUST be in the format of an email address.	null
info.license	The license information for the exposed API.
info.license.name	The license name used for the API.	null
info.license.url	A URL to the license used for the API. MUST be in the format of a URL. The url-field is mutually exclusive of the identifier-field.	null
info.license.identifier	An SPDX (https://spdx.org/licenses/) license expression for the API. The identifier-field is mutually exclusive of the url-field.	null
externalDocs	OpenAPI external docs configuration - link and description of an external documentation.
externalDocs.url	A URL to the external documentation.	"/"
externalDocs.description	A short description of the external documentation.	null
server	OpenAPI server configuration - an array of servers, which provide connectivity information to a target server. Multiple servers can be configured by repeating this block.	empty
server.url	A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served.	"/"
server.description	An optional string describing the host designated by the URL.	null
server.variable(name)	Server Variables for server URL template substitution. Multiple variables with different names can be specified by repeating this block	empty
server.variable(name).default	The default value to use for substitution. Must be in the list of enums.	null or the first entry in server.variable(name).enum
server.variable(name).enum	An enumeration of string values to be used if the substitution options are from a limited set. Must not be empty.	empty
server.variable(name).description	An optional description for this server variable.	null
security	Configuration for security and authentication.
security.defaultUnauthorizedResponse	Default response to automatically add to each protected route for the "Unauthorized"-Response-Code. Generated response can be overwritten with custom response. See TODO for more information.	null
security.defaultSecuritySchemeNames	The names of the security schemes available for use for the protected paths.	empty
security.securityScheme(schemeName)	Defines security schemes that can be used by operations. Multiple different security-schemes can be defined by repeating this block.
security.securityScheme(schemeName).description	A short description of the security scheme.	null
security.securityScheme(schemeName).type	The type of the security scheme. Can be API_KEY, HTTP, OAUTH2, OPENID_CONNECT or MUTUAL_TLS.	null
security.securityScheme(schemeName).name	The name scheme and of the header, query or cookie parameter to be used.	null
security.securityScheme(schemeName).scheme	The name of the HTTP Authorization scheme to be used. Required for type HTTP. Can be BASIC, BEARER, DIGEST, HOBA, MUTUAL, OAUTH, SCRAM_SHA_1, SCRAM_SHA_256 or VAPID.	null
security.securityScheme(schemeName).location	The location of the API key. Required for type API_KEY. Can be QUERY, HEADER or COOKIE.	null
security.securityScheme(schemeName).bearerFormat	A hint to the client to identify how the bearer token is formatted. Used for type HTTP and schema BEARER.	null
security.securityScheme(schemeName).flow	Information for the oauth flow types supported. Required for type OAUTH2.	null
security.securityScheme(schemeName).flow.implicit	Configuration for the OAuth Implicit flow.	null
security.securityScheme(schemeName).flow.password	Configuration for the OAuth Resource Owner Password flow.	null
security.securityScheme(schemeName).flow.clientCredentials	Configuration for the OAuth Client Credentials flow.	null
security.securityScheme(schemeName).flow.authorizationCode	Configuration for the OAuth Authorization Code flow.	null
security.securityScheme(schemeName).flow.*.authorizationUrl	The authorization URL to be used for this flow.	null
security.securityScheme(schemeName).flow.*.tokenUrl	The token URL to be used for this flow.	null
security.securityScheme(schemeName).flow.*.refreshUrl	The URL to be used for obtaining refresh tokens.	null
security.securityScheme(schemeName).flow.*.scopes	The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it.	null
security.securityScheme(schemeName).openIdConnectUrl	OpenId Connect URL to discover OAuth2 configuration values. Required for type OPENID_CONNECT	null
tags	Configuration for openapi-tags.
tags.tagGenerator	Automatically add tags to the route with the given url. The returned (non-null) tags will be added to the tags specified in the route-specific documentation.	no-op
tags.tag(name)	Add additional information to tags used by the api-spec. Not all tags need to be declared here.
tags.tag(name).description	A short description for the tag.	null
tags.tag(name).externalDocUrl	The URL for additional external documentation for this tag.	null
tags.tag(name).externalDocDescription	A short description of additional external documentation for this tag.	null
outputFormat	Output format of the api spec, either JSON or YAML	JSON