Overview
CAS takes advantages of Swagger to produce API documentation automatically. The generated documentation supports all CAS endpoints and REST APIs provided they are made available to the runtime application context and are present in the overlay.
Support is enabled by including the following dependency in the overlay:
1
2
3
4
5
<dependency>
<groupId>org.apereo.cas</groupId>
<artifactId>cas-server-support-swagger</artifactId>
<version>${cas.version}</version>
</dependency>
1
implementation "org.apereo.cas:cas-server-support-swagger:${project.'cas.version'}"
1
2
3
4
5
6
7
8
9
dependencyManagement {
imports {
mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
}
}
dependencies {
implementation "org.apereo.cas:cas-server-support-swagger"
}
1
2
3
4
5
6
7
8
9
10
dependencies {
/*
The following platform references are included automatically and are listed for reference only.
implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
*/
implementation "org.apereo.cas:cas-server-support-swagger"
}
The following settings and properties are available from the CAS configuration catalog:
springdoc.allowed-localesAllowed locales for i18n.
Allowed locales for i18n.
springdoc.api-docs.enabledWhether to generate and serve an OpenAPI document.
falseWhether to generate and serve an OpenAPI document.
springdoc.api-docs.groups.enabledThe Enabled.
falseThe Enabled.
springdoc.api-docs.pathPath to the generated OpenAPI documentation.
Path to the generated OpenAPI documentation. For a yaml file, append ".yaml" to the path.
springdoc.api-docs.resolve-extensions-propertiesThe Resolve extensions properties.
falseThe Resolve extensions properties.
springdoc.api-docs.resolve-schema-propertiesThe Resolve schema properties.
falseThe Resolve schema properties.
springdoc.api-docs.versionThe OpenAPI version.
openapi-3-1The OpenAPI version.
springdoc.auto-tag-classesThe Auto tag classes.
trueThe Auto tag classes.
springdoc.cache.disabledThe Disabled.
falseThe Disabled.
springdoc.cache.max-entriesThe maximum number of OpenAPI descriptions to keep in the cache.
100The maximum number of OpenAPI descriptions to keep in the cache. One entry is cached per requested locale, so this bounds the memory an untrusted caller can make the cache consume by varying the Accept-Language header. The least recently used entry is evicted once the limit is reached. A non-positive value falls back to the default of #DEFAULT_MAX_ENTRIES rather than meaning "unlimited". Narrow it further with springdoc.allowed-locales.
springdoc.consumes-to-matchThe Consumes to match.
The Consumes to match.
springdoc.default-consumes-media-typeThe Default consumes media type.
The Default consumes media type.
springdoc.default-flat-param-objectThe param default flatten
falseThe param default flatten
springdoc.default-produces-media-typeThe Default produces media type.
The Default produces media type.
springdoc.default-support-form-dataconvert query param to form data when consumes is multipart/form-data
falseconvert query param to form data when consumes is multipart/form-data
springdoc.disable-i18nThe Disable i18n.
falseThe Disable i18n.
springdoc.enable-data-restThe Enable hateoas.
trueThe Enable hateoas.
springdoc.enable-default-api-docsThe Enable default api docs.
trueThe Enable default api docs.
springdoc.enable-extra-schemasThe Enable extra schemas resolution.
falseThe Enable extra schemas resolution.
springdoc.enable-groovyThe Enable groovy.
trueThe Enable groovy.
springdoc.enable-hateoasThe Enable hateoas.
trueThe Enable hateoas.
springdoc.enable-javadocThe Enable javadoc.
trueThe Enable javadoc.
springdoc.enable-kotlinThe Enable kotlin.
trueThe Enable kotlin.
springdoc.enable-spring-securityThe Enable spring security.
trueThe Enable spring security.
springdoc.explicit-object-schemaSet explicit-object-schema to true to always include type: object in the schema, or to false to omit type: object.
falseSet explicit-object-schema to true to always include type: object in the schema, or to false to omit type: object.
springdoc.group-configsThe Group configs.
The Group configs.
springdoc.headers-to-matchThe Headers to match.
The Headers to match.
springdoc.login-endpoint.password-exampleThe example value for the password field of the login request body.
The example value for the password field of the login request body. Only applied when springdoc.show-login-endpoint=true.
springdoc.login-endpoint.username-exampleThe example value for the username field of the login request body.
The example value for the username field of the login request body. Only applied when springdoc.show-login-endpoint=true.
springdoc.model-and-view-allowedThe Model and view allowed.
falseThe Model and view allowed.
springdoc.model-converters.deprecating-converter.enabledThe Enabled.
falseThe Enabled.
springdoc.model-converters.pageable-converter.enabledThe Enabled.
falseThe Enabled.
springdoc.model-converters.polymorphic-converter.enabledThe Enabled.
falseThe Enabled.
springdoc.nullable-request-parameter-enabledThe Nullable request parameter enabled.
falseThe Nullable request parameter enabled.
springdoc.open-apiThe Open api.
The Open api.
springdoc.override-with-generic-responseThe Override with generic response.
The Override with generic response.
springdoc.packages-to-excludeThe Packages to exclude.
The Packages to exclude.
springdoc.packages-to-scanThe Packages to scan.
The Packages to scan.
springdoc.paths-to-excludeThe Paths to exclude.
The Paths to exclude.
springdoc.paths-to-matchThe Paths to match.
The Paths to match.
springdoc.pre-loading-enabledAllow for pre-loading OpenAPI
falseAllow for pre-loading OpenAPI
springdoc.pre-loading-localeslocale list to pre-loading
locale list to pre-loading
springdoc.produces-to-matchThe Produces to match.
The Produces to match.
springdoc.remove-broken-reference-definitionsThe Remove broken reference definitions.
trueThe Remove broken reference definitions.
springdoc.show-actuatorThe Show actuator.
falseThe Show actuator.
springdoc.show-login-endpointThe Show login endpoint.
falseThe Show login endpoint.
springdoc.show-oauth2-endpointsThe Show oauth 2 endpoint.
falseThe Show oauth 2 endpoint.
springdoc.show-spring-cloud-functionsThe Show spring cloud functions.
trueThe Show spring cloud functions.
springdoc.sort-converter.enabledThe Enabled.
falseThe Enabled.
springdoc.swagger-ui.config-urlURL to fetch external configuration document from.
URL to fetch external configuration document from.
springdoc.swagger-ui.csrf.cookie-nameThe Cookie name.
The Cookie name.
springdoc.swagger-ui.csrf.enabledThe Enabled.
falseThe Enabled.
springdoc.swagger-ui.csrf.header-nameThe Header name.
The Header name.
springdoc.swagger-ui.csrf.local-storage-keyThe Local storage key.
The Local storage key.
springdoc.swagger-ui.csrf.session-storage-keyThe Session storage key.
The Session storage key.
springdoc.swagger-ui.csrf.use-local-storageUse Local storage.
falseUse Local storage.
springdoc.swagger-ui.csrf.use-session-storageUse Session storage.
falseUse Session storage.
springdoc.swagger-ui.deep-linkingEnables or disables deep linking for tags and operations.
Enables or disables deep linking for tags and operations. @see deep-linking.md
springdoc.swagger-ui.default-model-expand-depthThe default expansion depth for the model on the model-example section.
The default expansion depth for the model on the model-example section.
springdoc.swagger-ui.default-model-renderingControls how the model is shown when the API is first rendered.
Controls how the model is shown when the API is first rendered.
springdoc.swagger-ui.default-models-expand-depthThe default expansion depth for models (set to -1 completely hide the models).
The default expansion depth for models (set to -1 completely hide the models).
springdoc.swagger-ui.disable-swagger-default-urlThe Disable swagger default url.
falseThe Disable swagger default url.
springdoc.swagger-ui.display-operation-idControls the display of operationId in operations list.
Controls the display of operationId in operations list.
springdoc.swagger-ui.display-request-durationControls the display of the request duration (in milliseconds) for Try-It-Out requests.
Controls the display of the request duration (in milliseconds) for Try-It-Out requests.
springdoc.swagger-ui.doc-expansionControls the default expansion setting for the operations and tags.
Controls the default expansion setting for the operations and tags.
springdoc.swagger-ui.document-titleThe Document title.
The Document title.
springdoc.swagger-ui.enabledWhether to generate and serve an OpenAPI document.
falseWhether to generate and serve an OpenAPI document.
springdoc.swagger-ui.filterIf set, enables filtering.
If set, enables filtering. The top bar will show an edit box that could be used to filter the tagged operations that are shown.
springdoc.swagger-ui.groups-orderThe Groups order.
ascThe Groups order.
springdoc.swagger-ui.layoutThe name of a component available via the plugin system to use as the top-level layout for Swagger UI.
The name of a component available via the plugin system to use as the top-level layout for Swagger UI.
springdoc.swagger-ui.max-displayed-tagsIf set, limits the number of tagged operations displayed to at most this many.
If set, limits the number of tagged operations displayed to at most this many.
springdoc.swagger-ui.oauth.additional-query-string-paramsThe Additional query string params.
The Additional query string params.
springdoc.swagger-ui.oauth.app-nameThe App name.
The App name.
springdoc.swagger-ui.oauth.client-idThe Client id.
The Client id.
springdoc.swagger-ui.oauth.client-secretThe Client secret.
The Client secret.
springdoc.swagger-ui.oauth.config-parameters
springdoc.swagger-ui.oauth.realmThe Realm.
The Realm.
springdoc.swagger-ui.oauth.scope-separatorThe Scope separator.
The Scope separator.
springdoc.swagger-ui.oauth.scopesThe Scopes selected by default upon authentication.
The Scopes selected by default upon authentication.
springdoc.swagger-ui.oauth.use-basic-authentication-with-access-code-grantThe Use basic authentication with access code grant.
The Use basic authentication with access code grant.
springdoc.swagger-ui.oauth.use-pkce-with-authorization-code-grantThe Use pkce with authorization code grant.
The Use pkce with authorization code grant.
springdoc.swagger-ui.oauth2-redirect-urlOAuth redirect URL.
OAuth redirect URL.
springdoc.swagger-ui.operations-sorterApply a sort to the operation list of each API
Apply a sort to the operation list of each API
springdoc.swagger-ui.pathThe path for the Swagger UI pages to load.
The path for the Swagger UI pages to load.
springdoc.swagger-ui.persist-authorizationThe Persist authorization.
The Persist authorization.
springdoc.swagger-ui.query-config-enabledThe Query config enabled.
The Query config enabled.
springdoc.swagger-ui.show-common-extensionsControls the display of extensions
Controls the display of extensions
springdoc.swagger-ui.show-extensionsControls the display of vendor extension (x-) fields and values.
Controls the display of vendor extension (x-) fields and values.
springdoc.swagger-ui.supported-submit-methodsThe supported try it out methods
The supported try it out methods
springdoc.swagger-ui.syntax-highlight.activatedThe Activated.
The Activated.
springdoc.swagger-ui.syntax-highlight.themeThe Theme.
The Theme.
springdoc.swagger-ui.tags-sorterApply a sort to the tag list of each API
Apply a sort to the tag list of each API
springdoc.swagger-ui.try-it-out-enabledTry it out enabled
Try it out enabled
springdoc.swagger-ui.urlThe Url.
The Url.
springdoc.swagger-ui.urlsThe Urls.
The Urls.
springdoc.swagger-ui.urls-primary-nameThe Urls primary name.
The Urls primary name.
springdoc.swagger-ui.use-root-pathThe Use root path.
falseThe Use root path.
springdoc.swagger-ui.validator-urlURL to validate specs against.
URL to validate specs against.
springdoc.swagger-ui.versionThe Swagger ui version.
The Swagger ui version.
springdoc.swagger-ui.with-credentialsThe With credentials.
The With credentials.
springdoc.trim-kotlin-indentThe trim kotlin indent.
falseThe trim kotlin indent.
springdoc.use-arbitrary-schemasWhen set to true, schemas without a defined type will be deserialized as an ArbitrarySchema (with no type), instead of an ObjectSchema with type: object.
falseWhen set to true, schemas without a defined type will be deserialized as an ArbitrarySchema (with no type), instead of an ObjectSchema with type: object.
springdoc.use-fqnUse fully qualified name
falseUse fully qualified name
springdoc.use-management-portIf set to true, exposes the swagger-ui on the actuator management port.
falseIf set to true, exposes the swagger-ui on the actuator management port.
springdoc.writer-with-default-pretty-printerThe Writer with default pretty printer.
falseThe Writer with default pretty printer.
springdoc.writer-with-order-by-keysThe Writer with order by keys.
falseThe Writer with order by keys.
Required settings may be needed to activate or affect the feature; review them even when they have a default. Optional settings only need to be set to change a default or to turn on the behavior they control. Third party settings belong to libraries such as Spring Boot that CAS builds on; their own documentation may have more detail.
Groovy scripting
CAS takes advantage of Apache Groovy in forms of either embedded or external scripts that allow one to, by default, dynamically build constructs, attributes, access strategies and a lot more. To activate the functionality described here, you may need to prepare CAS to support and integrate with Apache Groovy.
Please review this guide to configure your build.
Notes on configuration
Configuration Metadata
The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.
Be Selective
This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.
YAGNI
Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.
Naming Convention
Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all
forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where
this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those
that might be presented to the system via an external library or framework such as Spring Boot, etc.
Note
When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value.
The only possible exception to this rule is when naming actuator endpoints; The name of the
actuator endpoints (i.e. ssoSessions) MUST remain in camelCase mode.
Settings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided
to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with
the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition
or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the
way you intend.
Validation
Configuration properties are automatically validated on CAS startup to report issues with configuration binding, especially if defined CAS settings cannot be recognized or validated by the configuration schema. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.
Indexed Settings
CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be
incremented by the adopter to allow for distinct multiple configuration blocks.
Endpoints
The following Swagger endpoints may be used to analyze and test the APIs:
| Description | URL |
|---|---|
| Swagger API Specification | https://sso.example.org/cas/v3/api-docs |
| Swagger UI | https://sso.example.org/cas/swagger-ui.html |