| Parameter name | +Default Value | +Description | +
|---|---|---|
springdoc.api-docs.path |
+
|
+
|
+
springdoc.api-docs.enabled |
+
|
+
|
+
springdoc.packages-to-scan |
+
|
+
|
+
springdoc.paths-to-match |
+
|
+
|
+
springdoc.produces-to-match |
+
|
+
|
+
springdoc.headers-to-match |
+
|
+
|
+
springdoc.consumes-to-match |
+
|
+
|
+
springdoc.paths-to-exclude |
++ |
|
+
springdoc.packages-to-exclude |
++ |
|
+
springdoc.default-consumes-media-type |
+
|
+
|
+
springdoc.default-produces-media-type |
+
|
+
|
+
springdoc.cache.disabled |
+
|
+
|
+
springdoc.show-actuator |
+
|
+
|
+
springdoc.auto-tag-classes |
+
|
+
|
+
springdoc.model-and-view-allowed |
+
|
+
|
+
springdoc.override-with-generic-response |
+
|
+
|
+
springdoc.group-configs[0].group |
++ |
|
+
springdoc.group-configs[0].display-name |
++ |
|
+
springdoc.group-configs[0].packages-to-scan |
+
|
+
|
+
springdoc.group-configs[0].paths-to-match |
+
|
+
|
+
springdoc.group-configs[0].paths-to-exclude |
+`` |
+
|
+
springdoc.group-configs[0].packages-to-exclude |
++ |
|
+
springdoc.group-configs[0].produces-to-match |
+
|
+
|
+
springdoc.group-configs[0].consumes-to-match |
+
|
+
|
+
springdoc.group-configs[0].headers-to-match |
+
|
+
|
+
springdoc.webjars.prefix |
+
|
+
|
+
springdoc.api-docs.resolve-schema-properties |
+
|
+
|
+
springdoc.remove-broken-reference-definitions |
+
|
+
|
+
springdoc.writer-with-default-pretty-printer |
+
|
+
|
+
springdoc.model-converters.deprecating-converter.enabled |
+
|
+
|
+
springdoc.model-converters.polymorphic-converter.enabled |
+
|
+
|
+
springdoc.model-converters.pageable-converter.enabled |
+
|
+
|
+
springdoc.model-converters.sort-converter.enabled |
+
|
+
|
+
springdoc.use-fqn |
+
|
+
|
+
springdoc.show-login-endpoint |
+
|
+
|
+
springdoc.pre-loading-locales |
++ |
|
+
springdoc.writer-with-order-by-keys |
+
|
+
|
+
springdoc.use-management-port |
+
|
+
|
+
springdoc.disable-i18n |
+
|
+
|
+
springdoc.show-spring-cloud-functions |
+
|
+
|
+
springdoc.enable-groovy |
+
|
+
|
+
springdoc.enable-spring-security |
+
|
+
|
+
springdoc.enable-kotlin |
+
|
+
|
+
springdoc.enable-hateoas |
+
|
+
|
+
springdoc.enable-data-rest |
+
|
+
|
+
springdoc.api-docs.version |
+
|
+
|
+
springdoc.default-flat-param-object |
+
|
+
|
+
springdoc.default-support-form-data |
+
|
+
|
+
springdoc.nullable-request-parameter-enabled |
+
|
+
|
+
springdoc.show-oauth2-endpoints |
+
|
+
|
+
springdoc.api-docs.resolve-extensions-properties |
+
|
+
|
+
springdoc.enable-default-api-docs |
+
|
+
|
+
springdoc.trim-kotlin-indent |
+
|
+
|
+
springdoc.allowed-locales |
++ |
|
+
springdoc.enable-extra-schemas |
+
|
+
|
+
springdoc.explicit-object-schema |
+
|
+
|
+
springdoc.use-arbitrary-schemas |
+
|
+
|
+
Demo Spring Boot 3 WebFlux with Functional endpoints OpenAPI 3
+
+You can define your own groups of API based on the combination of: API paths and packages to scan. Each group should have a unique groupName.
+The OpenAPI description of this group, will be available by default on:
http://server:port/context-path/v3/api-docs/groupName
To enable the support of multiple OpenAPI definitions, a bean of type GroupedOpenApi needs to be defined.
For the following Group definition(based on package path), the OpenAPI description URL will be : /v3/api-docs/stores
+@Bean
+public GroupedOpenApi storeOpenApi() {
+ String paths[] = {"/store/**"};
+ return GroupedOpenApi.builder().group("stores").pathsToMatch(paths)
+ .build();
+}
+For the following Group definition (based on package name), the OpenAPI description URL will be: /v3/api-docs/users
+@Bean
+public GroupedOpenApi userOpenApi() {
+ String packagesToscan[] = {"test.org.springdoc.api.app68.api.user"};
+ return GroupedOpenApi.builder().group("users").packagesToScan(packagesToscan)
+ .build();
+}
+For the following Group definition(based on path), the OpenAPI description URL will be: /v3/api-docs/pets
+@Bean
+public GroupedOpenApi petOpenApi() {
+ String paths[] = {"/pet/**"};
+ return GroupedOpenApi.builder().group("pets").pathsToMatch(paths)
+ .build();
+}
+For the following Group definition (based on package name and path), the OpenAPI description URL will be: /v3/api-docs/groups
+@Bean
+public GroupedOpenApi groupOpenApi() {
+ String paths[] = {"/v1/**"};
+ String packagesToscan[] = {"test.org.springdoc.api.app68.api.user", "test.org.springdoc.api.app68.api.store"};
+ return GroupedOpenApi.builder().group("groups").pathsToMatch(paths).packagesToScan(packagesToscan)
+ .build();
+}
+For more details about the usage, you can have a look at the following sample Test:
+The support of the swagger official properties is available on springdoc-openapi. See Official documentation.
You can use the same swagger properties in the documentation as Spring Boot properties.
+| + + | +
+All these properties should be declared with the following prefix: springdoc.swagger-ui
+ |
+
You can use the standard swagger-ui property filter.
springdoc.swagger-ui.filter=group-a+
This property helps you disable only the UI.
+springdoc.swagger-ui.enabled=false+
You can set this property in your application.yml like so for example:
+springdoc.swagger-ui.doc-expansion= none+
swagger-ui?For layout options, you can use swagger-ui configuration options. For example:
+springdoc.swagger-ui.layout=BaseLayout+
You can use the following springdoc-openapi properties:
#For sorting endpoints alphabetically +springdoc.swagger-ui.operationsSorter=alpha +#For sorting tags alphabetically +springdoc.swagger-ui.tagsSorter=alpha+
You have to set the following property:
+springdoc.swagger-ui.supportedSubmitMethods=get, put, post, delete, options, head, patch, trace+
You should add @Schema(enumAsRef = true) on your enum.
enumAsRef = true to all enums ?Declare the following property:
+static {
+ io.swagger.v3.core.jackson.ModelResolver.enumsAsRef = true;
+}
+You can set list of paths to include using the following property:
+springdoc.pathsToMatch=/v1, /api/balance/**+
You can set list of packages to include using the following property:
+springdoc.packagesToScan=package1, package2+
These can be set by creating a swaggerUiConfig bean as follows:
@Bean
+@Primary
+fun swaggerUiConfig(config: SwaggerUiConfigProperties): SwaggerUiConfigProperties {
+ config.showCommonExtensions = true
+ config.queryConfigEnabled = true
+ return config
+}
+You can use the following annotation on the top of the field that you want to hide:
+@Schema(hidden = true)
@AuthenticationPrincipal parameter from spring-security ?A solution workaround would be to use: @Parameter(hidden = true)
The projects that use spring-boot-starter-security or spring-security-oauth2-authorization-server should use:
springdoc-openapi-starter-webmvc-api if they depend on spring-boot-starter-web and they only need the access to the OpenAPI endpoints.
OR springdoc-openapi-starter-webmvc-ui, if they depend on spring-boot-starter-web and they also need the access to the swagger-ui.
OR springdoc-openapi-starter-webflux-api if they depend on spring-boot-starter-webflux and they only the access to the OpenAPI endpoints.
OR springdoc-openapi-starter-webflux-ui, if they depend on spring-boot-starter-webflux and they also need the access to the swagger-ui.
Yes. More details are available, in the gradle plugin section.
+You can use @Parameter(hidden = true)
springdoc-openapi support Jersey?If you are using JAX-RS and as implementation Jersey (@Path for example), we do not support it.
We only support exposing Rest Endpoints using Spring managed beans (@RestController for example).
You can have a look at swagger-jaxrs2 project:
+ +springdoc-openapi generate API only for @RestController?@RestController is equivalent to @Controller + @RequestMapping on the type level.
For some legacy apps, we are constrained to still support both.
+If you need to hide the @Controller on the type level, in this case, you can use: @Hidden on controller level.
Please note this annotation can be also used to hide some methods from the generated documentation.
+@NotEmpty @NotBlank @PositiveOrZero @NegativeOrZero?Yes
+Pageable (spring-data-commons) object to correct URL-Parameter in Swagger UI?The support for Pageable of spring-data-commons is available out-of-the box since springdoc-openapi v1.6.0.
+For this, you have to combine @ParameterObject annotation with the Pageable type.
Before springdoc-openapi v1.6.0:
You can use as well @ParameterObject instead of @PageableAsQueryParam for HTTP GET methods.
static {
+ getConfig().replaceParameterObjectWithClass(org.springframework.data.domain.Pageable.class, Pageable.class)
+ .replaceParameterObjectWithClass(org.springframework.data.domain.PageRequest.class, Pageable.class);
+}
+Another solution, is to configure Pageable manually:
+you will have to declare the explicit mapping of Pageable fields as Query Params and add the @Parameter(hidden = true) Pageable pageable on your pageable parameter.
You should also, declare the annotation @PageableAsQueryParam provided by springdoc-openapi on the method level, or declare your own if need to define your custom description, defaultValue, …
If you want to disable the support of spring Pageable Type, you can use:
+springdoc.model-converters.pageable-converter.enabled=false| + + | +
+The property springdoc.model-converters.pageable-converter.enabled is only available since v1.5.11+
+ |
+
You could add a property allowableValues, to @Parameter. For example:
@GetMapping("/example")
+public Object example(@Parameter(name ="json", schema = @Schema(description = "var 1",type = "string", allowableValues = {"1", "2"}))
+String json) {
+ return null;
+}
+or you could override toString on your enum:
@Override
+@JsonValue
+public String toString() {
+ return String.valueOf(action);
+}
+springdoc-openapi-starter-webmvc-ui behind a reverse proxy?If your application is running behind a proxy, a load-balancer or in the cloud, the request information (like the host, port, scheme…) might change along the way. Your application may be running on 10.10.10.10:8080, but HTTP clients should only see example.org.
RFC7239 "Forwarded Headers" defines the Forwarded HTTP header; proxies can use this header to provide information about the original request. You can configure your application to read those headers and automatically use that information when creating links and sending them to clients in HTTP 302 responses, JSON documents or HTML pages. There are also non-standard headers, like X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Proto, X-Forwarded-Ssl, and X-Forwarded-Prefix.
If the proxy adds the commonly used X-Forwarded-For and X-Forwarded-Proto headers, setting server.forward-headers-strategy to NATIVE is enough to support those. With this option, the Web servers themselves natively support this feature; you can check their specific documentation to learn about specific behavior.
You need to make sure the following header is set in your reverse proxy configuration: X-Forwarded-Prefix
For example, using Apache 2, configuration:
+RequestHeader set X-Forwarded-Prefix "/custom-path"+
Then, in your Spring Boot application make sure your application handles this header: X-Forwarded-For. There are two ways to achieve this:
server.use-forward-headers=true+
If this is not enough, Spring Framework provides a ForwardedHeaderFilter. You can register it as a Servlet Filter in your application by setting server.forward-headers-strategy is set to FRAMEWORK.
Since Spring Boot 2.2, this is the new property to handle reverse proxy headers:
+server.forward-headers-strategy=frameworkAnd you can add the following bean to your application:
+@Bean
+ForwardedHeaderFilter forwardedHeaderFilter() {
+ return new ForwardedHeaderFilter();
+}
+If you need to manually adjust the URL displayed in the Swagger UI, implement the ServerBaseUrlCustomizer interface. This might be necessary to remove the port number, for example.
@Bean
+public class CustomServerBaseUrlCustomizer implements ServerBaseUrlCustomizer {
+ @Override
+ public String customize(String serverBaseUrl) {
+ try {
+ URL url = new URL(serverBaseUrl);
+ if (url.getHost().contains(".com")) {
+ serverBaseUrl = new URL(url.getProtocol(),url.getHost(),url.getFile()).toString();
+ }
+ } catch (MalformedURLException ex) {
+ // nothing we can do
+ }
+
+ return serverBaseUrl;
+ }
+}
+springdoc-openapi-starter-webmvc-ui dependency breaks my public/index.html welcome pageIf you already have static content on your root, and you don’t want it to be overridden by springdoc-openapi-starter-webmvc-ui configuration, you can just define a custom configuration of the swagger-ui, in order not to override the configuration of your files from in your context-root:
For example use:
+springdoc.swagger-ui.path= /swagger-ui/api-docs.html+
You can write your own implementation of OpenApiCustomizer.
An example is available on:
+ +@Bean
+public OpenApiCustomizer consumerTypeHeaderOpenAPICustomizer() {
+return openApi -> openApi.getPaths().values().stream().flatMap(pathItem -> pathItem.readOperations().stream())
+ .forEach(operation -> operation.addParametersItem(new HeaderParameter().$ref("#/components/parameters/myConsumerTypeHeader")));
+}
+| + + | +
+This bean OpenApiCustomizer will be applied to the Default OpenAPI only.
+ |
+
If you need the OpenApiCustomizer to applied to GroupedOpenApi as well, then use GlobalOpenApiCustomizer instead.
It is be possible to handle as return an empty content as response using, one of the following syntaxes:
+content = @Content
content = @Content(schema = @Schema(hidden = true))
For example:
+@Operation(summary = "Get thing", responses = {
+ @ApiResponse(description = "Successful Operation", responseCode = "200", content = @Content(mediaType = "application/json", schema = @Schema(implementation = String.class))),
+ @ApiResponse(responseCode = "404", description = "Not found", content = @Content),
+ @ApiResponse(responseCode = "401", description = "Authentication Failure", content = @Content(schema = @Schema(hidden = true))) })
+@RequestMapping(path = "/testme", method = RequestMethod.GET)
+ResponseEntity<String> testme() {
+ return ResponseEntity.ok("Hello");
+}
+An overloaded method on the same class, with the same HTTP Method and path, will have as a result, only one OpenAPI Operation generated.
+In addition, it’s recommended to have the @Operation in the level of one of the overloaded methods. Otherwise it might be overridden if it’s declared many times within the same overloaded method.
You can use springdoc-openapi-maven-plugin for this functionality:
You can customise the output directory (property outputDir): The default value is: ${project.build.directory}
+Principal, Locale, HttpServletRequest and HttpServletResponse and other injectable parameters supported by Spring MVC are excluded.
Full documentation here:
+ +If you don’t want to ignore the types Principal, Locale, HttpServletRequest, and others,:
SpringDocUtils.getConfig().removeRequestWrapperToIgnore(HttpServletRequest.class)
+You should add the @SecurityRequirement tags to your protected APIs.
For example:
+@Operation(security = { @SecurityRequirement(name = "bearer-key") })
+And the security definition sample:
+@Bean
+ public OpenAPI customOpenAPI() {
+ return new OpenAPI()
+ .components(new Components()
+ .addSecuritySchemes("bearer-key",
+ new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")));
+}
+OAS 3 was released in July 2017, and there was no release of springfox to support OAS 3.
+springfox covers for the moment only swagger 2 integration with Spring Boot. The latest release date is June 2018. So, in terms of maintenance there is a big lack of support lately.
We decided to move forward and share the library that we already used on our internal projects, with the community.
+The biggest difference with springfox, is that we integrate new features not covered by springfox:
The integration between Spring Boot and OpenAPI 3 standard.
+We rely on on swagger-annotations and swagger-ui only official libraries.
We support new features on Spring 5, like spring-webflux with annotated and functional style.
We do our best to answer all the questions and address all issues or enhancement requests
+There is no relation between springdoc-openapi and springfox.If you want to migrate to OpenAPI 3:
Remove all the dependencies and the related code to springfox
+Add springdoc-openapi-starter-webmvc-ui dependency
If you don’t want to serve the UI from your root path or there is a conflict with an existing configuration, you can just change the following property:
+springdoc.swagger-ui.path=/you-path/swagger-ui.html+
You may have global parameters with Standard OpenAPI description.
+If you need the definitions to appear globally (within every group), no matter if the group fulfills the conditions specified on the GroupedOpenApi , you can use OpenAPI Bean.
+You can define common parameters under parameters in the global components section and reference them elsewhere via $ref. You can also define global header parameters.
For this, you can override to OpenAPI Bean, and set the global headers or parameters definition on the components level.
+@Bean
+public OpenAPI customOpenAPI(@Value("${springdoc.version}") String appVersion) {
+ return new OpenAPI()
+ .components(new Components().addSecuritySchemes("basicScheme", new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic"))
+ .addParameters("myHeader1", new Parameter().in("header").schema(new StringSchema()).name("myHeader1")).addHeaders("myHeader2", new Header().description("myHeader2 header").schema(new StringSchema())))
+ .info(new Info()
+ .title("Petstore API")
+ .version(appVersion)
+ .description("This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.")
+ .termsOfService("http://swagger.io/terms/")
+ .license(new License().name("Apache 2.0").url("http://springdoc.org")));
+}
+You can use: @SecurityScheme annotation.
Or you can define it programmatically, by overriding OpenAPI Bean:
+ @Bean
+ public OpenAPI customOpenAPI(@Value("${springdoc.version}") String appVersion) {
+ return new OpenAPI()
+ .components(new Components().addSecuritySchemes("basicScheme",
+ new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic")))
+ info(new Info().title("SpringShop API").version(appVersion)
+ .license(new License().name("Apache 2.0").url("http://springdoc.org")));
+ }
+You can use @io.swagger.v3.oas.annotations.Hidden annotation at @RestController, @RestControllerAdvice and method level
The @Hidden annotation on exception handler methods, is considered when building generic (error) responses from @ControllerAdvice exception handlers.
Or use: @Operation(hidden = true)
For global SecurityScheme, you can add it inside your own OpenAPI definition:
+@Bean
+public OpenAPI customOpenAPI() {
+ return new OpenAPI().components(new Components()
+ .addSecuritySchemes("basicScheme", new SecurityScheme()
+ .type(SecurityScheme.Type.HTTP).scheme("basic"))).info(new Info().title("Custom API")
+ .version("100")).addTagsItem(new Tag().name("mytag"));
+}
+The support of spring property resolver for @Info: title * description * version * termsOfService
The support of spring property resolver for @Info.license: name * url
The support of spring property resolver for @Info.contact: name * email * url
The support of spring property resolver for @Operation: description * summary
The support of spring property resolver for @Parameter: description * name
The support of spring property resolver for @ApiResponse: description
Its also possible to declare security URLs for @OAuthFlow: openIdConnectUrl * authorizationUrl * refreshUrl * tokenUrl
The support of spring property resolver for @Schema: name * title * description , by setting springdoc.api-docs.resolve-schema-properties to true
The support of spring property resolver for @ExtensionProperty by setting springdoc.api-docs.resolve-extensions-properties to true
Generating automatically server URL may be useful, if the documentation is not present.
+If the server annotations are present, they will be used instead.
+By default, the OpenAPI description is calculated once, and then cached.
+Sometimes the same swagger-ui is served behind internal and external proxies. some users want the server URL, to be computed on each http request.
+In order to disable springdoc cache, you will have to set the following property:
+springdoc.cache.disabled= true+
swagger-ui?You should use the springdoc-openapi-core dependency only:
<dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
+ <version>latest.version</version>
+</dependency>springdoc-openapi endpoints ?Use the following property:
+springdoc.api-docs.enabled=false+
To hide the response element, using @Schema annotation, as follows, at operation level:
@Operation(responses = @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(hidden = true))))+
Or directly at @ApiResponses level:
@ApiResponses(value = {@ApiResponse(responseCode = "200", content = @Content(schema = @Schema(hidden = true))) })
+OR
+@ApiResponse(responseCode = "404", description = "Not found", content = @Content)
+swagger-ui, when I set a different context-path?If you use different context-path:
+server.servlet.context-path= /foo+
The swagger-ui will be available on the following URL:
http://server:port/foo/swagger-ui.html
You can Define your own OpenAPI Bean: If you need the definitions to appear globally (within every group), no matter if the group fulfills the conditions specified on the GroupedOpenApi , you can use OpenAPI Bean.
+@Bean
+public OpenAPI customOpenAPI(@Value("${springdoc.version}") String appVersion) {
+ return new OpenAPI()
+ .components(new Components().addSecuritySchemes("basicScheme",
+ new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic")))
+ .info(new Info().title("SpringShop API").version(appVersion)
+ .license(new License().name("Apache 2.0").url("http://springdoc.org")));
+}
+If you need the definitions to appear within a specific group, and respect the conditions specified on the GroupedOpenApi, you can add OpenApiCustomizer to your GroupedOpenApi definition.
+GroupedOpenApi.builder().group("users").pathsToMatch(paths).packagesToScan(packagedToMatch).addOpenApiCustomizer(customerGlobalHeaderOpenApiCustomizer())
+ .build()
+
+@Bean
+public OpenApiCustomizer customerGlobalHeaderOpenApiCustomizer() {
+ return openApi -> openApi.path("/foo",
+ new PathItem().get(new Operation().operationId("foo").responses(new ApiResponses()
+ .addApiResponse("default",new ApiResponse().description("")
+ .content(new Content().addMediaType("fatz", new MediaType()))))));
+}
+The source code of the application is available at the following GitHub repository:
+ +The library supports the main file types: MultipartFile, @RequestPart, FilePart
You can upload a file as follows:
+@PostMapping(value = "/upload", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
+public ResponseEntity<?> upload(@Parameter(description = "file") final MultipartFile file) {
+ return null;
+}
+
+@PostMapping(value = "/uploadFileWithQuery", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
+public ResponseEntity<?> uploadFileWithQuery(@Parameter(description = "file") @RequestPart("file") final MultipartFile file,
+ @Parameter(description = "An extra query parameter") @RequestParam String name) {
+ return null;
+}
+
+@PostMapping(value = "/uploadFileWithJson", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE}, produces = {
+ MediaType.APPLICATION_JSON_VALUE})
+public ResponseEntity<?> uploadFileWithJson(
+ @RequestBody(content = @Content(encoding = @Encoding(name = "jsonRequest", contentType = MediaType.APPLICATION_JSON_VALUE)))
+ @Parameter(description = "An extra JSON payload sent with file") @RequestPart("jsonRequest") final JsonRequest jsonRequest,
+ @RequestPart("file") final MultipartFile file) {
+ return null;
+}
+Any @GetMapping parameters is marked as required, even if @RequestParam is missing.
You can add @Parameter(required=false) annotation if you need different behaviour.
Query parameters with defaultValue specified are marked as required.
springdoc-openapi renders these methods as a single endpoint. It detects the overloaded endpoints, and generates parameters.schema.oneOf.
With this property, all the springdoc-openapi auto-configuration beans are disabled:
springdoc.api-docs.enabled=false+
Then enable the minimal Beans configuration, by adding this Bean:
+@Bean
+SpringDocConfiguration springDocConfiguration(){
+ return new SpringDocConfiguration();
+}
+
+@Bean
+SpringDocConfigProperties springDocConfigProperties() {
+ return new SpringDocConfigProperties();
+}
+
+@Bean
+ObjectMapperProvider objectMapperProvider(SpringDocConfigProperties springDocConfigProperties){
+ return new ObjectMapperProvider(springDocConfigProperties);
+}
+Then configure, the path of your custom UI yaml file.
+springdoc.swagger-ui.url=/api-docs.yaml+
The OpenAPI 3 specification does not allow explicitly adding Authorization header.
+Note: Header parameters named Accept, Content-Type and Authorization are not allowed. To describe these headers
For more information, you can read:
+ +This is the default behaviour if your @Controller doesn’t have annotation @ResponseBody
You can change your controllers to @RestControllers. Or add @ResponseBody + @Controller.
If its not possible, you can configure springdoc to scan you additional controller using SpringDocUtils. For example:
+static {
+ SpringDocUtils.getConfig().addRestControllers(HelloController.class);
+}
+You can load groups dynamically using spring-boot configuration files.
+Note that, for this usage, you don’t have to declare the GroupedOpenApi Bean.
+You need to declare the following properties, under the prefix springdoc.group-configs.
+For example:
+springdoc.group-configs[0].group=users +springdoc.group-configs[0].paths-to-match=/user/** +springdoc.group-configs[0].packages-to-scan=test.org.springdoc.api+
The list of properties under this prefix, are available here:
+You can use springdoc annotation @ParameterObject.
+Request parameter annotated with @ParameterObject will help adding each field of the parameter as a separate request parameter.
+This is compatible with Spring MVC request parameters mapping to POJO object.
+This annotation does not support nested parameter objects.
+POJO object must contain getters for fields with mandatory prefix get. Otherwise, the swagger documentation will not show the fields of the annotated entity.
springdoc-openapi SNAPSHOT ?For testing purposes only, you can test temporarily using the last springdoc-openapi SNAPSHOT
To achieve that, configure your pom.xml file with the following <repositories> section:
<repositories>
+ <repository>
+ <name>Central Portal Snapshots</name>
+ <id>central-portal-snapshots</id>
+ <url>https://central.sonatype.com/repository/maven-snapshots/</url>
+ <releases>
+ <enabled>false</enabled>
+ </releases>
+ <snapshots>
+ <enabled>true</enabled>
+ </snapshots>
+ </repository>
+ </repositories>springdoc-openapi MonetaryAmount support ?If an application wants to enable the springdoc-openapi support, it declares:
SpringDocUtils.getConfig().replaceWithClass(MonetaryAmount.class, org.springdoc.core.converters.models.MonetaryAmount.class);
+Another solution, without using springdoc-openapi MonetaryAmount, would be:
+SpringDocUtils.getConfig().replaceWithSchema(MonetaryAmount.class, new ObjectSchema()
+ .addProperties("amount", new NumberSchema()).example(99.96)
+ .addProperties("currency", new StringSchema().example("USD")));
+The properties springdoc.swagger-ui.urls.*, are suitable to configure external (/v3/api-docs url).
+For example if you want to agreagte all the endpoints of other services, inside one single application.
+IMPORTANT: Don’t forget that CORS needs to be enabled as well.
If your file open-api.json, contains the OpenAPI documentation in OpenAPI 3 format. +Then simply declare: The file name can be anything you want, from the moment your declaration is consistent yaml or json OpenAPI Spec.
+ springdoc.swagger-ui.url=/open-api.jsonThen the file open-api.json, should be located in: src/main/resources/static +No additional configuration is needed.
+If you are using standard headers.( For example using spring-security headers) +If the CSRF Token is required, swagger-ui automatically sends the new XSRF-TOKEN during each HTTP REQUEST.
+If your XSRF-TOKEN isn’t standards-based, you can use a requestInterceptor to manually capture and attach the latest xsrf token to requests programmatically via spring resource transformer:
+Starting from release v1.4.4 of springdoc-openapi, a new property is added to enable CSRF support, while using standard header names:
+springdoc.swagger-ui.csrf.enabled=trueYou can use the following property:
+springdoc.swagger-ui.disable-swagger-default-url=trueYes, you can use it in conjunction with @ParameterObject annotation.
+Also, the spring-boot spring.data.web. and spring.data.rest.default. properties are supported since v1.4.5
You can use the following property:
+springdoc.show-login-endpoint=trueYou can use the following property:
+springdoc.remove-broken-reference-definitions=falseThe whole idea of springdoc-openapi is to get your documentation the closest to the code, with minimal code changes.
+If the code contains @Deprecated, sprindoc-openapi will consider its schema as Deprecated as well.
+If you want to declare a field on swagger as non deprecated, even with the java code, the field contains @Depreacted,
+You can use the following property that is available since release v1.4.3:
springdoc.model-converters.deprecating-converter.enabled=falseYou can use the following property:
+springdoc.model-and-view-allowed=trueYou can use the following property:
+springdoc.writer-with-default-pretty-printer=trueComplex objects are always resolved as a reference to a schema defined in components.
+For example let’s consider a Instance class with an workAddress and homeAddress attribute of type Address:
public class PersonDTO {
+
+ @JsonProperty
+ private String email;
+
+ @JsonProperty
+ private String firstName;
+
+ @JsonProperty
+ private String lastName;
+
+ @Schema(ref = "WorkAddressSchema")
+ @JsonProperty
+ private Address workAddress;
+
+ @Schema(ref = "HomeAddressSchema")
+ @JsonProperty
+ private Address homeAddress;
+
+}
+
+public class Address {
+
+ @JsonProperty
+ private String addressName;
+
+}
+If you want to define two different schemas for this class, you can set up 2 different schemas as follow:
+@Bean
+public OpenAPI customOpenAPI() {
+return new OpenAPI().components(new Components()
+.addSchemas("WorkAddressSchema", getSchemaWithDifferentDescription(Address.class, "work Address" ))
+.addSchemas("HomeAddressSchema", getSchemaWithDifferentDescription(Address.class, "home Address" )));
+}
+
+private Schema getSchemaWithDifferentDescription(Class className, String description){
+ResolvedSchema resolvedSchema = ModelConverters.getInstance()
+.resolveAsResolvedSchema(
+new AnnotatedType(className).resolveAsRef(false));
+return resolvedSchema.schema.description(description);
+}
+For example let’s consider a Instance class with an email attribute:
public class PersonDTO {
+
+ @JsonProperty
+ private String email;
+
+ @JsonProperty
+ private String firstName;
+
+ @JsonProperty
+ private String lastName;
+
+
+}
+If you want to define two different description for the email, you can set up 2 different schemas as follow:
@Bean
+public OpenAPI customOpenAPI() {
+return new OpenAPI().components(new Components()
+.addSchemas("PersonDTO1", getFieldSchemaWithDifferentDescription(PersonDTO.class, "work email" ))
+.addSchemas("PersonDTO2", getFieldSchemaWithDifferentDescription(PersonDTO.class, "home email" )));
+}
+
+private Schema getFieldSchemaWithDifferentDescription(Class className, String description){
+ ResolvedSchema resolvedSchema = ModelConverters.getInstance()
+ .resolveAsResolvedSchema(
+ new AnnotatedType(className).resolveAsRef(false));
+ return resolvedSchema.schema.addProperties("email", new StringSchema().description(description));
+}
+You can customize swagger documentation static resources located in META-INF/resources/webjars/swagger-ui/{swagger.version}/. The list of resources includes:
index.html
swagger-ui-bundle.js
swagger-ui.css
swagger-ui-standalone-preset.js
swagger-ui.css.map
swagger-ui-bundle.js.map
swagger-ui-standalone-preset.js.map
favicon-32x32.png
To do this, you need to extend the implementation of SwaggerIndexPageTransformer
public class SwaggerCodeBlockTransformer
+ extends SwaggerIndexPageTransformer {
+ // < constructor >
+ @Override
+ public Resource transform(HttpServletRequest request,
+ Resource resource,
+ ResourceTransformerChain transformer)
+ throws IOException {
+ if (resource.toString().contains("swagger-ui.css")) {
+ final InputStream is = resource.getInputStream();
+ final InputStreamReader isr = new InputStreamReader(is);
+ try (BufferedReader br = new BufferedReader(isr)) {
+ final String css = br.lines().collect(Collectors.joining());
+ final byte[] transformedContent = css.replace("old", "new").getBytes();
+ return new TransformedResource(resource, transformedContent);
+ } // AutoCloseable br > isr > is
+ }
+ return super.transform(request, resource, transformer);
+ }
+
+}
+Next, add transformer @Bean to your @Configuration
@Configuration
+public class OpenApiConfig {
+ @Bean
+ public SwaggerIndexTransformer swaggerIndexTransformer(
+ SwaggerUiConfigProperties a,
+ SwaggerUiOAuthProperties b,
+ SwaggerUiConfigParameters c,
+ SwaggerWelcomeCommon d) {
+ return new SwaggerCodeBlockTransformer(a, b, c, d);
+ }
+}
+Illustrative example
+
+The native support available added in spring-boot 3. +If you have some time, do not hesitate to test it before the next release.
+For the OpenAPI REST endpoints, you just need to build your application with the spring native profile.
If you give @OpenAPIDefinition or @SecurityScheme to a class that has no implementation, that class will disappear when you natively compile.
+To avoid this, give the class a @Configuration.
@Configuration
+@OpenAPIDefinition(info = @Info(title = "My App", description = "description"))
+public class OpenAPIConfig {
+}
+When your application is using spring without (spring-boot), you need to add beans and auto-configuration that are natively provided in spring-boot.
+For example, lets assume you want load the swagger-ui in spring-mvc application:
+You mainly, need to add the springdoc-openapi module
+<dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+ <version>last.version</version>
+</dependency>If you don’t have the spring-boot and spring-boot-autoconfigure dependencies, you need to add them. And pay attention to the compatibility matrix, between you spring.version and spring-boot.version. For example, in this case (spring.version=5.1.12.RELEASE):
+ <dependency>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-autoconfigure</artifactId>
+ <version>3.3.3</version>
+ </dependency>Scan for the springdoc-openapi 'auto-configuration classes that spring-boot automatically loads for you.
Depending on your module, you can find them on the file: spring.factories of each springdoc-openapi module.
@Configuration
+@EnableWebMvc
+public class WebConfig implements WebApplicationInitializer {
+
+ @Override
+ public void onStartup(ServletContext servletContext) {
+ WebApplicationContext context = getContext();
+ servletContext.addListener(new ContextLoaderListener(context));
+ ServletRegistration.Dynamic dispatcher = servletContext.addServlet("RestServlet",
+ new DispatcherServlet(context));
+ dispatcher.setLoadOnStartup(1);
+ dispatcher.addMapping("/*");
+ }
+
+ private AnnotationConfigWebApplicationContext getContext() {
+ AnnotationConfigWebApplicationContext context = new AnnotationConfigWebApplicationContext();
+ context.register(this.getClass(),
+ SpringDocConfiguration.class,
+ SpringDocConfigProperties.class,
+ SpringDocSpecPropertiesConfiguration.class,
+ SpringDocWebMvcConfiguration.class,
+ MultipleOpenApiSupportConfiguration.class,
+ SwaggerConfig.class,
+ SwaggerUiConfigProperties.class,
+ SwaggerUiOAuthProperties.class,
+ );
+ return context;
+ }
+}
+Depending on your module, you can find them on the file: org.springframework.boot.autoconfigure.AutoConfiguration.imports of each springdoc-openapi module.
For groups usage make sure your GroupedOpenApi Beans are scanned.
If additionally, you are using custom context path: /my-servlet-path. Make sure you declare the following property:
spring.mvc.servlet.path=/my-servlet-path+
springdoc-openapi with spring-boot ?springdoc-openapi 2.x is compatible with spring-boot 3.
In general, you should only pick the last stable version as per today 2.8.9.
+More precisely, this the exhaustive list of spring-boot versions against which springdoc-openapi has been built:
Spring Boot Versions |
+Springdoc OpenAPI Versions |
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
Swagger UI unable to render definition, when overriding the default spring registered HttpMessageConverter?When overriding the default spring-boot registered HttpMessageConverter, you should have ByteArrayHttpMessageConverter registered as well to have proper springdoc-openapi support.
converters.add(new ByteArrayHttpMessageConverter());
+ converters.add(new MappingJackson2HttpMessageConverter(jacksonBuilder.build()));
+| + + | +
+Order is very important, when registering HttpMessageConverters.
+ |
+
The issue is caused by the changes introduced by Spring-Boot 3.2.0
+in particular for the Parameter Name Discovery.
+This can be fixed by adding the -parameters arg to the Maven Compiler Plugin.
<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <parameters>true</parameters>
+ </configuration>
+</plugin>The library uses spring-boot application auto-configured packages to scan for the following annotations in spring beans: OpenAPIDefinition and Info. +These annotations declare, API Information: Title, version, licence, security, servers, tags, security and externalDocs. +For better performance of documentation generation, declare @OpenAPIDefinition and @SecurityScheme annotations within a spring managed bean.
+To generate documentation automatically, make sure all the methods declare the HTTP Code responses using the annotation: @ResponseStatus
+springdoc-openapi endpointsIn order to disable the springdoc-openapi endpoint (/v3/api-docs by default) use the following property:
# Disabling the /v3/api-docs endpoint
+springdoc.api-docs.enabled=falseIn order to disable the swagger-ui, use the following property:
+# Disabling the swagger-ui
+springdoc.swagger-ui.enabled=falseThe library supports the swagger-ui official properties:
+You need to declare swagger-ui properties as spring-boot properties. +All these properties should be declared with the following prefix: springdoc.swagger-ui
+Additionally, to @Hidden annotation from swagger-annotations, its possible to restrict the generated OpenAPI description using package or path configuration.
+For the list of packages to include, use the following property:
+# Packages to include
+springdoc.packagesToScan=com.package1, com.package2For the list of paths to include, use the following property:
+# Paths to include
+springdoc.pathsToMatch=/v1, /api/balance/**Since version v1.5.0, a functional DSL has been introduced, thanks to this enhancement in the spring-framework: #25938
+It’s an alternative functional API to the @RouterOperations annotations.
This is a sample DSL, to generate OpenAPI description to the webflux/WebMvc.fn REST endpoints:
+@Bean
+RouterFunction<?> routes() {
+ return route().GET("/foo", HANDLER_FUNCTION, ops -> ops
+ .operationId("hello")
+ .parameter(parameterBuilder().name("key1").description("My key1 description"))
+ .parameter(parameterBuilder().name("key2").description("My key2 description"))
+ .response(responseBuilder().responseCode("200").description("This is normal response description"))
+ .response(responseBuilder().responseCode("404").description("This is another response description"))
+ ).build();
+}
+Here is the link for some sample codes:
+And the Demo code, using the functional endpoints DSL:
+Since version v1.3.8, the support of functional endpoints has been added.
+Two main annotations have been added for this purpose: @RouterOperations and @RouterOperation.
Only REST APIs with the @RouterOperations and @RouterOperation can be displayed on the swagger-ui.
@RouterOperation: It can be used alone, if the Router bean contains one single route related to the REST API..
+When using @RouterOperation, its not mandatory to fill the path
@RouterOperation, can reference directly a spring Bean (beanClass property) and the underlying method (beanMethod property): Springdoc-openapi, will then inspect this method and the swagger annotations on this method level.
@Bean
+@RouterOperation(beanClass = EmployeeService.class, beanMethod = "findAllEmployees")
+RouterFunction<ServerResponse> getAllEmployeesRoute() {
+ return route(GET("/employees").and(accept(MediaType.APPLICATION_JSON)),
+ req -> ok().body(
+ employeeService().findAllEmployees(), Employee.class));
+}
+@RouterOperation, contains the @Operation annotation.
+The @Operation annotation can also be placed on the bean method level if the property beanMethod is declared.
| + + | ++Don’t forget to set operationId which is mandatory. + | +
@Bean
+@RouterOperation(operation = @Operation(operationId = "findEmployeeById", summary = "Find purchase order by ID", tags = { "MyEmployee" },
+ parameters = { @Parameter(in = ParameterIn.PATH, name = "id", description = "Employee Id") },
+ responses = { @ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(implementation = Employee.class))),
+ @ApiResponse(responseCode = "400", description = "Invalid Employee ID supplied"),
+ @ApiResponse(responseCode = "404", description = "Employee not found") }))
+RouterFunction<ServerResponse> getEmployeeByIdRoute() {
+ return route(GET("/employees/{id}"),
+ req -> ok().body(
+ employeeRepository().findEmployeeById(req.pathVariable("id")), Employee.class));
+}
+@RouterOperations: This annotation should be used if the Router bean contains multiple routes.
+When using RouterOperations, its mandatory to fill the path property.
A @RouterOperations, contains many @RouterOperation.
@RouterOperations({ @RouterOperation(path = "/getAllPersons", beanClass = PersonService.class, beanMethod = "getAll"),
+ @RouterOperation(path = "/getPerson/{id}", beanClass = PersonService.class, beanMethod = "getById"),
+ @RouterOperation(path = "/createPerson", beanClass = PersonService.class, beanMethod = "save"),
+ @RouterOperation(path = "/deletePerson/{id}", beanClass = PersonService.class, beanMethod = "delete") })
+@Bean
+public RouterFunction<ServerResponse> personRoute(PersonHandler handler) {
+ return RouterFunctions
+ .route(GET("/getAllPersons").and(accept(MediaType.APPLICATION_JSON)), handler::findAll)
+ .andRoute(GET("/getPerson/{id}").and(accept(MediaType.APPLICATION_STREAM_JSON)), handler::findById)
+ .andRoute(POST("/createPerson").and(accept(MediaType.APPLICATION_JSON)), handler::save)
+ .andRoute(DELETE("/deletePerson/{id}").and(accept(MediaType.APPLICATION_JSON)), handler::delete);
+}
+All the documentations filled using @RouterOperation, might be completed by the router function data.
+For that, @RouterOperation fields must help identify uniquely the concerned route.
+springdoc-openpi scans for a unique route related to a @RouterOperation annotation, using on the following criteria:
by path
+by path and RequestMethod
+by path and produces
+by path and consumes
+by path and RequestMethod and produces
+by path and RequestMethod and consumes
+by path and produces and consumes
+by path and RequestMethod and produces and consumes
+Some code samples are available on GITHUB of demos:
+And some project tests: (from app69 to app75)
+For the integration between spring-boot and swagger-ui, add the library to the list of your project dependencies (No additional configuration is needed)
+ <dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+ <version>2.8.9</version>
+ </dependency>This will automatically deploy swagger-ui to a spring-boot application:
+Documentation will be available in HTML format, using the official swagger-ui jars
+The Swagger UI page will then be available at http://server:port/context-path/swagger-ui.html and the OpenAPI description will be available at the following url for json format: http://server:port/context-path/v3/api-docs
server: The server name or IP
+port: The server port
+context-path: The context path of the application
+Documentation will be available in yaml format as well, on the following path : /v3/api-docs.yaml
+| + + | ++For custom path of the swagger documentation in HTML format, add a custom springdoc property, in your spring-boot configuration file: . + | +
# swagger-ui custom path
+springdoc.swagger-ui.path=/swagger-ui.htmlspringdoc-openapi endpointsswagger-ui?enumAsRef = true to all enums ?@AuthenticationPrincipal parameter from spring-security ?@Parameters annotation supported ?springdoc-openapi support Jersey?springdoc-openapi generate API only for @RestController?@NotEmpty @NotBlank @PositiveOrZero @NegativeOrZero?Pageable (spring-data-commons) object to correct URL-Parameter in Swagger UI?springdoc-openapi-starter-webmvc-ui behind a reverse proxy?@JsonView annotations in Spring MVC APIs supported?springdoc-openapi-starter-webmvc-ui dependency breaks my public/index.html welcome pageswagger-ui?springdoc-openapi endpoints ?swagger-ui, when I set a different context-path?@Parameter inside @Operation annotation?springdoc-openapi SNAPSHOT ?springdoc-openapi MonetaryAmount support ?springdoc-openapi with spring-boot ?Swagger UI unable to render definition, when overriding the default spring registered HttpMessageConverter?| + + | +
+springdoc-openapi v1.8.0 is the latest Open Source release supporting Spring Boot 2.x and 1.x.+An extended support for springdoc-openapi v1 project is now available for organizations that need support beyond 2023. +For more details, feel free to reach out: sales@springdoc.org + |
+
springdoc-openapi is on Open Collective. If you ❤️ this project consider becoming a sponsor.
This project is sponsored by
+springdoc-openapi java library helps to automate the generation of API documentation using spring boot projects.
+springdoc-openapi works by examining an application at runtime to infer API semantics based on spring configurations, class structure and various annotations.
Automatically generates documentation in JSON/YAML and HTML format APIs. +This documentation can be completed by comments using swagger-api annotations.
+This library supports:
+OpenAPI 3
+Spring-boot v3 (Java 17 & Jakarta EE 9)
+JSR-303, specifically for @NotNull, @Min, @Max, and @Size.
+Swagger-ui
+OAuth 2
+GraalVM native images
+The following video introduces the Library:
+
+This is a community-based project, not maintained by the Spring Framework Contributors (Pivotal).
+For the integration between spring-boot and swagger-ui, add the library to the list of your project dependencies (No additional configuration is needed)
+
<dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+ <version>2.8.9</version>
+ </dependency>This will automatically deploy swagger-ui to a spring-boot application:
+Documentation will be available in HTML format, using the official swagger-ui jars
+The Swagger UI page will then be available at http://server:port/context-path/swagger-ui.html and the OpenAPI description will be available at the following url for json format: http://server:port/context-path/v3/api-docs
server: The server name or IP
+port: The server port
+context-path: The context path of the application
+Documentation will be available in yaml format as well, on the following path : /v3/api-docs.yaml
+| + + | ++For custom path of the swagger documentation in HTML format, add a custom springdoc property, in your spring-boot configuration file: . + | +
# swagger-ui custom path
+springdoc.swagger-ui.path=/swagger-ui.htmlDocumentation will be available at the following url for json format: http://server:port/context-path/v3/api-docs
server: The server name or IP
+port: The server port
+context-path: The context path of the application
+Documentation will be available in yaml format as well, on the following path : /v3/api-docs.yaml
+Add the library to the list of your project dependencies. (No additional configuration is needed)
+
+ <dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
+ <version>2.8.9</version>
+ </dependency>| + + | ++This dependency is relevant if you want to generate the OpenAPI description without using the swagger-ui. + | +
| + + | ++For custom path of the OpenAPI documentation in Json format, add a custom springdoc property, in your spring-boot configuration file: + | +
# /api-docs endpoint custom path
+springdoc.api-docs.path=/api-docsDocumentation will be available in yaml format as well, on the following path : /v3/api-docs.yaml
+Add the library to the list of your project dependencies (No additional configuration is needed)
+ <dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-starter-webflux-api</artifactId>
+ <version>2.8.9</version>
+ </dependency>The support for Spring Hateoas is available using the dependency springdoc-openapi-hateoas.
+The projects that use spring-boot-starter-hateoas should use:
springdoc-openapi-starter-webmvc-api if they need only the access to the OpenAPI endpoints
OR springdoc-openapi-starter-webmvc-ui, if they need also the access to the swagger-ui
springdoc-openapi project supports spring-boot-starter-data-rest types like: @RepositoryRestResource and QuerydslPredicate annotations.
The projects that use spring-boot-starter-data-rest should use:
springdoc-openapi-starter-webmvc-api if they need only the access to the OpenAPI endpoints
OR springdoc-openapi-starter-webmvc-ui, if they need also the access to the swagger-ui
springdoc-openapi helps ignoring @AuthenticationPrincipal type in case it is used on REST Controllers.
springdoc-openapi supports also exposing Oauth2 endpoints of spring-security-oauth2-authorization-server.
The projects that use spring-boot-starter-security or spring-security-oauth2-authorization-server should use:
springdoc-openapi-starter-webmvc-api if they depend on spring-boot-starter-web and they only need the access to the OpenAPI endpoints.
OR springdoc-openapi-starter-webmvc-ui, if they depend on spring-boot-starter-web and they also need the access to the swagger-ui.
OR springdoc-openapi-starter-webflux-api if they depend on spring-boot-starter-webflux and they only the access to the OpenAPI endpoints.
OR springdoc-openapi-starter-webflux-ui, if they depend on spring-boot-starter-webflux and they also need the access to the swagger-ui.
In order to display spring-boot-actuator endpoints, simply add the following property:
springdoc.show-actuator=trueStarting from the release 1.5.1, it will be possible to expose the swagger-ui and the openapi endpoints on actuator port.
| + + | ++The actuator management port has to be different from the application port. + | +
To expose the swagger-ui, on the management port, you should set
+springdoc.use-management-port=true
+# This property enables the openapi and swagger-ui endpoints to be exposed beneath the actuator base path.
+management.endpoints.web.exposure.include=openapi, swagger-uiOnce enabled, you should also be able to see the springdoc-openapi endpoints under: (host and port depends on your settings)
+- http://serverName:managementPort/actuator
For example, if you have the following settings:
+Two endpoints will be available:
+REST API that holdes the OpenAPI definition:
+http://serverName:managementPort/actuator/openapi
An Endpoint, that routes to the swagger-ui:
+http://serverName:managementPort/actuator/swagger-ui
management.server.port=9090For the example, you should also be able to see the springdoc-openapi endpoints:
+http://serverName:9090/actuator
http://serverName:9090/actuator/swagger-ui
http://serverName:9090/actuator/openapi
All the path springdoc-openapi properties are not applicable when springdoc.use-management-port=true.
| + + | +
+If you want to reach the application endpoints, from the swagger-ui deployed beneath the actuator base path, using a different port from your application, CORS for your endpoints on your application level should be enabled.
+ |
+
Additionally, it is also possible to combine this property, with the existing property to display the actuator endpoints in the swagger-ui.
+springdoc.show-actuator=trueOnce enabled: +- A dedicated group for the actuator endpoints will be by default added. +- If no group is defined for the application, a default one will be added.
+The swagger-ui will be then accessible through the actuator port:
+http://serverName:managementPort/actuator/swagger-ui
If the management port is different from the application port and springdoc.use-management-port is not defined but springdoc.show-actuator is set to true:
The swagger-ui will be then accessible through the application port. For example: http://serverName:applicationPort/swagger-ui.html
A dedicated group for the actuator endpoints will be by default added.
+If no group is defined for the application, a default one will be added.
+| + + | +
+If you want to reach the actuator endpoints for this case (different port from your application), CORS for your actuator endpoints should be enabled.
+ |
+
Note: The naming of these new endpoints beneath the actuator base path cannot be customized for now.
+spring-cloud-function-web exposes Java Function as REST endpoint automatically.
+* Since version v1.6.3, the support of functional endpoints has been added.
These starters will display the OpenAPI description of the spring-cloud-function-web endpoints.
If you are using spring-web, simply add the springdoc-openapi-starter-webmvc-ui dependency.
If you are using spring-webflux, simply add the springdoc-openapi-starter-webflux-ui dependency.
The customisation of the output can be achieved programmatically through OpenApiCustomizer or with the annotations: @RouterOperations and @RouterOperation.
+For annotation usage, you have:
+* @RouterOperation: It can be used alone, if the customisation is related to a single REST API.
+When using @RouterOperation, it’s not mandatory to fill the path
@RouterOperation, contains the @Operation annotation.
+The @Operation annotation can also be placed on the bean method level if the property beanMethod is declared.
| + + | ++Don’t forget to set operationId which is mandatory. + | +
@Bean
+@RouterOperation(operation = @Operation(description = "Say hello", operationId = "hello", tags = "persons",
+ responses = @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = PersonDTO.class)))))
+public Supplier<PersonDTO> helloSupplier() {
+ return () -> new PersonDTO();
+}
+@RouterOperations: This annotation should be used to describe the multiple REST APIs exposed by spring-cloud-function-web.
+When using RouterOperations, it’s mandatory to fill the method property.
A @RouterOperations, contains many @RouterOperation.
@Bean
+@RouterOperations({
+ @RouterOperation(method = RequestMethod.GET, operation = @Operation(description = "Say hello GET", operationId = "lowercaseGET", tags = "persons")),
+ @RouterOperation(method = RequestMethod.POST, operation = @Operation(description = "Say hello POST", operationId = "lowercasePOST", tags = "positions"))
+})
+public Function<Flux<String>, Flux<String>> lowercase() {
+ return flux -> flux.map(value -> value.toLowerCase());
+}
+Some code samples are available on GITHUB of demos:
+springdoc-openapi supports Kotlin types.
The projects that use Kotlin should use:
springdoc-openapi-starter-webmvc-api if they depend on spring-boot-starter-web and they only need the access to the OpenAPI endpoints.
OR springdoc-openapi-starter-webmvc-ui, if they depend on spring-boot-starter-web and they also need the access to the swagger-ui.
OR springdoc-openapi-starter-webflux-api if they depend on spring-boot-starter-webflux and they only the access to the OpenAPI endpoints.
OR springdoc-openapi-starter-webflux-ui, if they depend on spring-boot-starter-webflux and they also need the access to the swagger-ui.
| + + | +
+In addition, your project should add jackson-module-kotlin as well to have the full support of Kotlin types:
+ |
+
<dependency>
+ <groupId>com.fasterxml.jackson.module</groupId>
+ <artifactId>jackson-module-kotlin</artifactId>
+ </dependency>The projects that use Groovy should use:
springdoc-openapi-starter-webmvc-api if they depend on spring-boot-starter-web and they only need the access to the OpenAPI endpoints.
OR springdoc-openapi-starter-webmvc-ui, if they depend on spring-boot-starter-web and they also need the access to the swagger-ui.
OR springdoc-openapi-starter-webflux-api if they depend on spring-boot-starter-webflux and they only the access to the OpenAPI endpoints.
OR springdoc-openapi-starter-webflux-ui, if they depend on spring-boot-starter-webflux and they also need the access to the swagger-ui.
springdoc-openapi can introspect Javadoc annotations and comments:
The javadoc comment of a method: is resolved as the @Operation description
@return : is resolved as the @Operation response description
The javadoc comment of an attribute: is resolved as '@Schema' description for this field.
+The projects that needs Javadoc support should use:
springdoc-openapi-starter-webmvc-api if they depend on spring-boot-starter-web and they only need the access to the OpenAPI endpoints.
OR springdoc-openapi-starter-webmvc-ui, if they depend on spring-boot-starter-web and they also need the access to the swagger-ui.
OR springdoc-openapi-starter-webflux-api if they depend on spring-boot-starter-webflux and they only the access to the OpenAPI endpoints.
OR springdoc-openapi-starter-webflux-ui, if they depend on spring-boot-starter-webflux and they also need the access to the swagger-ui.
| + + | +
+In addition, your project should add therapi-runtime-javadoc to read Javadoc comments at runtime.
+Ensure that you add it as well as its annotation processor to your project’s dependencies. Otherwise, the Javadoc support will fail silently.
+ |
+
<!--Annotation processor -->
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <annotationProcessorPaths>
+ <path>
+ <groupId>com.github.therapi</groupId>
+ <artifactId>therapi-runtime-javadoc-scribe</artifactId>
+ <version>0.15.0</version>
+ </path>
+ </annotationProcessorPaths>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+ <!-- Runtime library -->
+ <dependency>
+ <groupId>com.github.therapi</groupId>
+ <artifactId>therapi-runtime-javadoc</artifactId>
+ <version>0.15.0</version>
+ </dependency>| + + | ++If both a swagger-annotation description and a javadoc comment are present. The value of the swagger-annotation description will be used. + | +
Starting from version v2.8.7, springdoc-openapi provides a BOM (Bill of Materials) to manage the dependencies of the project.
+You can declare it in your project as follows:
<dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-bom</artifactId>
+ <version>2.8.9</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>The library uses spring-boot application auto-configured packages to scan for the following annotations in spring beans: OpenAPIDefinition and Info. +These annotations declare, API Information: Title, version, licence, security, servers, tags, security and externalDocs. +For better performance of documentation generation, declare @OpenAPIDefinition and @SecurityScheme annotations within a spring managed bean.
+To generate documentation automatically, make sure all the methods declare the HTTP Code responses using the annotation: @ResponseStatus
+springdoc-openapi endpointsIn order to disable the springdoc-openapi endpoint (/v3/api-docs by default) use the following property:
# Disabling the /v3/api-docs endpoint
+springdoc.api-docs.enabled=falseIn order to disable the swagger-ui, use the following property:
+# Disabling the swagger-ui
+springdoc.swagger-ui.enabled=falseThe library supports the swagger-ui official properties:
+You need to declare swagger-ui properties as spring-boot properties. +All these properties should be declared with the following prefix: springdoc.swagger-ui
+Additionally, to @Hidden annotation from swagger-annotations, its possible to restrict the generated OpenAPI description using package or path configuration.
+For the list of packages to include, use the following property:
+# Packages to include
+springdoc.packagesToScan=com.package1, com.package2For the list of paths to include, use the following property:
+# Paths to include
+springdoc.pathsToMatch=/v1, /api/balance/**Since version v1.5.0, a functional DSL has been introduced, thanks to this enhancement in the spring-framework: #25938
+It’s an alternative functional API to the @RouterOperations annotations.
This is a sample DSL, to generate OpenAPI description to the webflux/WebMvc.fn REST endpoints:
+@Bean
+RouterFunction<?> routes() {
+ return route().GET("/foo", HANDLER_FUNCTION, ops -> ops
+ .operationId("hello")
+ .parameter(parameterBuilder().name("key1").description("My key1 description"))
+ .parameter(parameterBuilder().name("key2").description("My key2 description"))
+ .response(responseBuilder().responseCode("200").description("This is normal response description"))
+ .response(responseBuilder().responseCode("404").description("This is another response description"))
+ ).build();
+}
+Here is the link for some sample codes:
+And the Demo code, using the functional endpoints DSL:
+Since version v1.3.8, the support of functional endpoints has been added.
+Two main annotations have been added for this purpose: @RouterOperations and @RouterOperation.
Only REST APIs with the @RouterOperations and @RouterOperation can be displayed on the swagger-ui.
@RouterOperation: It can be used alone, if the Router bean contains one single route related to the REST API..
+When using @RouterOperation, its not mandatory to fill the path
@RouterOperation, can reference directly a spring Bean (beanClass property) and the underlying method (beanMethod property): Springdoc-openapi, will then inspect this method and the swagger annotations on this method level.
@Bean
+@RouterOperation(beanClass = EmployeeService.class, beanMethod = "findAllEmployees")
+RouterFunction<ServerResponse> getAllEmployeesRoute() {
+ return route(GET("/employees").and(accept(MediaType.APPLICATION_JSON)),
+ req -> ok().body(
+ employeeService().findAllEmployees(), Employee.class));
+}
+@RouterOperation, contains the @Operation annotation.
+The @Operation annotation can also be placed on the bean method level if the property beanMethod is declared.
| + + | ++Don’t forget to set operationId which is mandatory. + | +
@Bean
+@RouterOperation(operation = @Operation(operationId = "findEmployeeById", summary = "Find purchase order by ID", tags = { "MyEmployee" },
+ parameters = { @Parameter(in = ParameterIn.PATH, name = "id", description = "Employee Id") },
+ responses = { @ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(implementation = Employee.class))),
+ @ApiResponse(responseCode = "400", description = "Invalid Employee ID supplied"),
+ @ApiResponse(responseCode = "404", description = "Employee not found") }))
+RouterFunction<ServerResponse> getEmployeeByIdRoute() {
+ return route(GET("/employees/{id}"),
+ req -> ok().body(
+ employeeRepository().findEmployeeById(req.pathVariable("id")), Employee.class));
+}
+@RouterOperations: This annotation should be used if the Router bean contains multiple routes.
+When using RouterOperations, its mandatory to fill the path property.
A @RouterOperations, contains many @RouterOperation.
@RouterOperations({ @RouterOperation(path = "/getAllPersons", beanClass = PersonService.class, beanMethod = "getAll"),
+ @RouterOperation(path = "/getPerson/{id}", beanClass = PersonService.class, beanMethod = "getById"),
+ @RouterOperation(path = "/createPerson", beanClass = PersonService.class, beanMethod = "save"),
+ @RouterOperation(path = "/deletePerson/{id}", beanClass = PersonService.class, beanMethod = "delete") })
+@Bean
+public RouterFunction<ServerResponse> personRoute(PersonHandler handler) {
+ return RouterFunctions
+ .route(GET("/getAllPersons").and(accept(MediaType.APPLICATION_JSON)), handler::findAll)
+ .andRoute(GET("/getPerson/{id}").and(accept(MediaType.APPLICATION_STREAM_JSON)), handler::findById)
+ .andRoute(POST("/createPerson").and(accept(MediaType.APPLICATION_JSON)), handler::save)
+ .andRoute(DELETE("/deletePerson/{id}").and(accept(MediaType.APPLICATION_JSON)), handler::delete);
+}
+All the documentations filled using @RouterOperation, might be completed by the router function data.
+For that, @RouterOperation fields must help identify uniquely the concerned route.
+springdoc-openpi scans for a unique route related to a @RouterOperation annotation, using on the following criteria:
by path
+by path and RequestMethod
+by path and produces
+by path and consumes
+by path and RequestMethod and produces
+by path and RequestMethod and consumes
+by path and produces and consumes
+by path and RequestMethod and produces and consumes
+Some code samples are available on GITHUB of demos:
+And some project tests: (from app69 to app75)
+springdoc-openapi relies on standard spring configuration properties (yml or properties) using the standard files locations.
| Parameter name | +Default Value | +Description | +
|---|---|---|
springdoc.api-docs.path |
+
|
+
|
+
springdoc.api-docs.enabled |
+
|
+
|
+
springdoc.packages-to-scan |
+
|
+
|
+
springdoc.paths-to-match |
+
|
+
|
+
springdoc.produces-to-match |
+
|
+
|
+
springdoc.headers-to-match |
+
|
+
|
+
springdoc.consumes-to-match |
+
|
+
|
+
springdoc.paths-to-exclude |
++ |
|
+
springdoc.packages-to-exclude |
++ |
|
+
springdoc.default-consumes-media-type |
+
|
+
|
+
springdoc.default-produces-media-type |
+
|
+
|
+
springdoc.cache.disabled |
+
|
+
|
+
springdoc.show-actuator |
+
|
+
|
+
springdoc.auto-tag-classes |
+
|
+
|
+
springdoc.model-and-view-allowed |
+
|
+
|
+
springdoc.override-with-generic-response |
+
|
+
|
+
springdoc.group-configs[0].group |
++ |
|
+
springdoc.group-configs[0].display-name |
++ |
|
+
springdoc.group-configs[0].packages-to-scan |
+
|
+
|
+
springdoc.group-configs[0].paths-to-match |
+
|
+
|
+
springdoc.group-configs[0].paths-to-exclude |
+`` |
+
|
+
springdoc.group-configs[0].packages-to-exclude |
++ |
|
+
springdoc.group-configs[0].produces-to-match |
+
|
+
|
+
springdoc.group-configs[0].consumes-to-match |
+
|
+
|
+
springdoc.group-configs[0].headers-to-match |
+
|
+
|
+
springdoc.webjars.prefix |
+
|
+
|
+
springdoc.api-docs.resolve-schema-properties |
+
|
+
|
+
springdoc.remove-broken-reference-definitions |
+
|
+
|
+
springdoc.writer-with-default-pretty-printer |
+
|
+
|
+
springdoc.model-converters.deprecating-converter.enabled |
+
|
+
|
+
springdoc.model-converters.polymorphic-converter.enabled |
+
|
+
|
+
springdoc.model-converters.pageable-converter.enabled |
+
|
+
|
+
springdoc.model-converters.sort-converter.enabled |
+
|
+
|
+
springdoc.use-fqn |
+
|
+
|
+
springdoc.show-login-endpoint |
+
|
+
|
+
springdoc.pre-loading-locales |
++ |
|
+
springdoc.writer-with-order-by-keys |
+
|
+
|
+
springdoc.use-management-port |
+
|
+
|
+
springdoc.disable-i18n |
+
|
+
|
+
springdoc.show-spring-cloud-functions |
+
|
+
|
+
springdoc.enable-groovy |
+
|
+
|
+
springdoc.enable-spring-security |
+
|
+
|
+
springdoc.enable-kotlin |
+
|
+
|
+
springdoc.enable-hateoas |
+
|
+
|
+
springdoc.enable-data-rest |
+
|
+
|
+
springdoc.api-docs.version |
+
|
+
|
+
springdoc.default-flat-param-object |
+
|
+
|
+
springdoc.default-support-form-data |
+
|
+
|
+
springdoc.nullable-request-parameter-enabled |
+
|
+
|
+
springdoc.show-oauth2-endpoints |
+
|
+
|
+
springdoc.api-docs.resolve-extensions-properties |
+
|
+
|
+
springdoc.enable-default-api-docs |
+
|
+
|
+
springdoc.trim-kotlin-indent |
+
|
+
|
+
springdoc.allowed-locales |
++ |
|
+
springdoc.enable-extra-schemas |
+
|
+
|
+
springdoc.explicit-object-schema |
+
|
+
|
+
springdoc.use-arbitrary-schemas |
+
|
+
|
+
The support of the swagger-ui properties is available on springdoc-openapi. See Official documentation.
You can use the same swagger-ui properties in the documentation as Spring Boot properties.
+| + + | +
+All these properties should be declared with the following prefix: springdoc.swagger-ui
+ |
+
| Parameter name | +Default Value | +Description | +
|---|---|---|
springdoc.swagger-ui.path |
+
|
+
|
+
springdoc.swagger-ui.enabled |
+
|
+
|
+
springdoc.swagger-ui.configUrl |
+
|
+
|
+
springdoc.swagger-ui.layout |
+
|
+
|
+
springdoc.swagger-ui.validatorUrl |
++ | By default, Swagger UI does not validate specs. You can use this parameter to set a validator URL, for example for against swagger.io’s online validator. |
+
springdoc.swagger-ui.tryItOutEnabled |
+
|
+
|
+
springdoc.swagger-ui.filter |
+
|
+
|
+
springdoc.swagger-ui.operationsSorter |
++ |
|
+
springdoc.swagger-ui.tagsSorter |
++ |
|
+
springdoc.swagger-ui.oauth2RedirectUrl |
+
|
+
|
+
springdoc.swagger-ui.displayOperationId |
+
|
+
|
+
springdoc.swagger-ui.displayRequestDuration |
+
|
+
|
+
springdoc.swagger-ui.deepLinking |
+
|
+
|
+
springdoc.swagger-ui.defaultModelsExpandDepth |
+
|
+
|
+
springdoc.swagger-ui.defaultModelExpandDepth |
+
|
+
|
+
springdoc.swagger-ui.defaultModelRendering |
++ |
|
+
springdoc.swagger-ui.docExpansion |
++ |
|
+
springdoc.swagger-ui.maxDisplayedTags |
++ |
|
+
springdoc.swagger-ui.showExtensions |
+
|
+
|
+
springdoc.swagger-ui.url |
++ |
|
+
springdoc.swagger-ui.showCommonExtensions |
+
|
+
|
+
springdoc.swagger-ui.supportedSubmitMethods |
++ |
|
+
springdoc.swagger-ui.queryConfigEnabled |
+
|
+
|
+
springdoc.swagger-ui.oauth. additionalQueryStringParams |
++ |
|
+
springdoc.swagger-ui.disable-swagger-default-url |
+
|
+
|
+
springdoc.swagger-ui.urls[0].url |
++ |
|
+
springdoc.swagger-ui.urls[0].name |
++ |
|
+
springdoc.swagger-ui.urlsPrimaryName |
++ |
|
+
springdoc.swagger-ui.oauth.clientId |
++ |
|
+
springdoc.swagger-ui.oauth.clientSecret |
++ |
|
+
springdoc.swagger-ui.oauth.realm |
++ |
|
+
springdoc.swagger-ui.oauth.appName |
++ |
|
+
springdoc.swagger-ui.oauth.scopeSeparator |
++ |
|
+
springdoc.swagger-ui.csrf.enabled |
+
|
+
|
+
springdoc.swagger-ui.csrf.use-local-storage |
+
|
+
|
+
springdoc.swagger-ui.csrf.use-session-storage |
+
|
+
|
+
springdoc.swagger-ui.csrf.cookie-name |
+
|
+
|
+
springdoc.swagger-ui.csrf.header-name |
+
|
+
|
+
springdoc.swagger-ui.syntaxHighlight.activated |
+
|
+
|
+
springdoc.swagger-ui.syntaxHighlight.theme |
+
|
+
|
+
springdoc.swagger-ui.oauth. useBasicAuthentication WithAccessCodeGrant |
+
|
+
|
+
springdoc.swagger-ui.oauth. usePkceWithAuthorization CodeGrant |
+
|
+
|
+
springdoc.swagger-ui.persistAuthorization |
+
|
+
|
+
springdoc.swagger-ui.use-root-path |
+
|
+
|
+
The aim of springdoc-openapi-maven-plugin is to generate json and yaml OpenAPI description during build time.
+The plugin works during integration-tests phase, and generate the OpenAPI description.
+The plugin works in conjunction with spring-boot-maven plugin.
You can test it during the integration tests phase using the maven command:
+mvn verifyIn order to use this functionality, you need to add the plugin declaration on the plugins section of your pom.xml:
+<plugin>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-maven-plugin</artifactId>
+ <version>${spring-boot-maven-plugin.version}</version>
+ <configuration>
+ <jvmArguments>-Dspring.application.admin.enabled=true</jvmArguments>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>start</goal>
+ <goal>stop</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
+<plugin>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-maven-plugin</artifactId>
+ <version>1.5</version>
+ <executions>
+ <execution>
+ <id>integration-test</id>
+ <goals>
+ <goal>generate</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>For more custom settings of the springdoc-openapi-maven-plugin, you can consult the plugin documentation:
+This plugin allows you to generate an OpenAPI 3 specification for a Spring Boot application from a Gradle build.
+plugins {
+ id("org.springframework.boot") version "3.1.2"
+ id("org.springdoc.openapi-gradle-plugin") version "1.9.0"
+}
+When you add this plugin and its runtime dependency plugins to your build file, the plugin creates the following tasks:
+forkedSpringBootRun
+generateOpenApiDocs
+gradle clean generateOpenApiDocsFor more custom configuration of springdoc-openapi-gradle-plugin ,you can consult the plugin documentation:
Demo Spring Boot 3 WebFlux with Functional endpoints OpenAPI 3
+
+All the modules have been renamed.
+springdoc-openapi-starter-common integrates many spring modules support in order to hide the maximum of complexity.
+It allows the support out of the box for Actuator / Spring Cloud Function / Spring Data Rest/ Spring Native/ Spring Hateoas / Spring Securtiy / Kotlin/ Javadoc.
The following table describes the main modules changes:
+| springdoc-openapi-v1 | +springdoc-openapi-v2 | +Description | +
|---|---|---|
|
+
|
+Includes foundation |
+
|
+
|
+For Spring Data Rest support |
+
|
+
|
+For Groovy support |
+
|
+
|
+For Spring Hateoas support |
+
|
+
|
+For Javadoc support |
+
|
+
|
+For Kotlin support |
+
|
+
|
+For Spring Security support |
+
|
+
|
+For Spring WebMvc support |
+
|
+
|
+For Spring WebFlux support |
+
|
+
|
+For using the Swagger-UI in a Spring WebMvc context |
+
|
+
|
+For using the Swagger-UI in a Spring WebFlux context |
+
| + + | ++classes/annotations changes + | +
| springdoc-openapi-v1 | +springdoc-openapi-v2 | +
|---|---|
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
| + + | ++Migration tips + | +
The following modules are not anymore needed and can be removed:
+springdoc-openapi-javadoc
springdoc-openapi-kotlin
springdoc-openapi-data-rest
springdoc-openapi-security
springdoc-openapi-webmvc-core
springdoc-openapi-webflux-core
springdoc-openapi-hateoas
springdoc-openapi-groovy
In addition:
+Replace springdoc-openapi-ui by springdoc-openapi-starter-webmvc-ui
Replace springdoc-openapi-webflux-ui by springdoc-openapi-starter-webflux-ui
Remove springfox and swagger 2 dependencies. Add springdoc-openapi-starter-webmvc-ui dependency instead.
<dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+ <version>2.8.9</version>
+ </dependency>Replace swagger 2 annotations with swagger 3 annotations (it is already included with springdoc-openapi-starter-webmvc-ui dependency).
+Package for swagger 3 annotations is io.swagger.v3.oas.annotations.
@Api → @Tag
@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(allowEmptyValue = true) → @Schema(nullable = true)
@ApiModelProperty → @Schema
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
@ApiParam → @Parameter
@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")
This step is optional: Only if you have multiple Docket beans replace them with GroupedOpenApi beans.
Before:
+ @Bean
+ public Docket publicApi() {
+ return new Docket(DocumentationType.SWAGGER_2)
+ .select()
+ .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public"))
+ .paths(PathSelectors.regex("/public.*"))
+ .build()
+ .groupName("springshop-public")
+ .apiInfo(apiInfo());
+ }
+
+ @Bean
+ public Docket adminApi() {
+ return new Docket(DocumentationType.SWAGGER_2)
+ .select()
+ .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.admin"))
+ .paths(PathSelectors.regex("/admin.*"))
+ .apis(RequestHandlerSelectors.withMethodAnnotation(Admin.class))
+ .build()
+ .groupName("springshop-admin")
+ .apiInfo(apiInfo());
+ }
+Now:
+ @Bean
+ public GroupedOpenApi publicApi() {
+ return GroupedOpenApi.builder()
+ .group("springshop-public")
+ .pathsToMatch("/public/**")
+ .build();
+ }
+ @Bean
+ public GroupedOpenApi adminApi() {
+ return GroupedOpenApi.builder()
+ .group("springshop-admin")
+ .pathsToMatch("/admin/**")
+ .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class))
+ .build();
+ }
+If you have only one Docket — remove it and instead add properties to your application.properties:
springdoc.packagesToScan=package1, package2
+springdoc.pathsToMatch=/v1, /api/balance/**Add bean of OpenAPI type. See example:
@Bean
+ public OpenAPI springShopOpenAPI() {
+ return new OpenAPI()
+ .info(new Info().title("SpringShop API")
+ .description("Spring shop sample application")
+ .version("v0.0.1")
+ .license(new License().name("Apache 2.0").url("http://springdoc.org")))
+ .externalDocs(new ExternalDocumentation()
+ .description("SpringShop Wiki Documentation")
+ .url("https://springshop.wiki.github.org/docs"));
+ }
+If the swagger-ui is served behind a proxy:
+ +To customise the Swagger UI
+To hide an operation or a controller from documentation
+ +springdoc-openapi is on Open Collective.
If you ❤️ this project consider becoming a sponsor.
+This money is used to cover project expenses and your donation will help the project live and grow successfully.
+Thank you to our bronze sponsors!
+
+
+ 
+
+
+ 
+
+
+ 
+
+
+ 
+
+
+ 
+
+
Bronze sponsors donate $50 per month to the project, and get the following benefits:
+You will receive a Sponsor badge 🎖!. Visibility on the front page of springdoc.org in the welcome page (about 55,000 views/month on May, 2022).
“Thank you” tweet from `springdoc team'.
+Silver sponsors donate $100 per month to the project, and get the following benefits:
+Same benefits as bronze sponsors (visibility on main pages, and thank you tweet).
+The ability to get support for 2 issues every month, non transferable.
If issues are not created by the end of the month, it is lost
+Gold sponsors donate $500 per month to the project, and get the following benefits:
+Same benefits as silver sponsors (visibility on main pages, and thank you tweet).
+The ability to get support for 10 issues every month, non transferable.
Company logos on all springdoc.org page footers
+If issues are not created by the end of the month, the remaining ones are lost.
+Thank you to The Spring Team for sharing all relevant resources around Spring projects.
+Thanks a lot JetBrains for supporting springdoc-openapi project.
+
+You can define your own groups of API based on the combination of: API paths and packages to scan. Each group should have a unique groupName.
+The OpenAPI description of this group, will be available by default on:
http://server:port/context-path/v3/api-docs/groupName
To enable the support of multiple OpenAPI definitions, a bean of type GroupedOpenApi needs to be defined.
For the following Group definition(based on package path), the OpenAPI description URL will be : /v3/api-docs/stores
+@Bean
+public GroupedOpenApi storeOpenApi() {
+ String paths[] = {"/store/**"};
+ return GroupedOpenApi.builder().group("stores").pathsToMatch(paths)
+ .build();
+}
+For the following Group definition (based on package name), the OpenAPI description URL will be: /v3/api-docs/users
+@Bean
+public GroupedOpenApi userOpenApi() {
+ String packagesToscan[] = {"test.org.springdoc.api.app68.api.user"};
+ return GroupedOpenApi.builder().group("users").packagesToScan(packagesToscan)
+ .build();
+}
+For the following Group definition(based on path), the OpenAPI description URL will be: /v3/api-docs/pets
+@Bean
+public GroupedOpenApi petOpenApi() {
+ String paths[] = {"/pet/**"};
+ return GroupedOpenApi.builder().group("pets").pathsToMatch(paths)
+ .build();
+}
+For the following Group definition (based on package name and path), the OpenAPI description URL will be: /v3/api-docs/groups
+@Bean
+public GroupedOpenApi groupOpenApi() {
+ String paths[] = {"/v1/**"};
+ String packagesToscan[] = {"test.org.springdoc.api.app68.api.user", "test.org.springdoc.api.app68.api.store"};
+ return GroupedOpenApi.builder().group("groups").pathsToMatch(paths).packagesToScan(packagesToscan)
+ .build();
+}
+For more details about the usage, you can have a look at the following sample Test:
+The support of the swagger official properties is available on springdoc-openapi. See Official documentation.
You can use the same swagger properties in the documentation as Spring Boot properties.
+| + + | +
+All these properties should be declared with the following prefix: springdoc.swagger-ui
+ |
+
You can use the standard swagger-ui property filter.
springdoc.swagger-ui.filter=group-a+
This property helps you disable only the UI.
+springdoc.swagger-ui.enabled=false+
You can set this property in your application.yml like so for example:
+springdoc.swagger-ui.doc-expansion= none+
swagger-ui?For layout options, you can use swagger-ui configuration options. For example:
+springdoc.swagger-ui.layout=BaseLayout+
You can use the following springdoc-openapi properties:
#For sorting endpoints alphabetically +springdoc.swagger-ui.operationsSorter=alpha +#For sorting tags alphabetically +springdoc.swagger-ui.tagsSorter=alpha+
You have to set the following property:
+springdoc.swagger-ui.supportedSubmitMethods=get, put, post, delete, options, head, patch, trace+
You should add @Schema(enumAsRef = true) on your enum.
enumAsRef = true to all enums ?Declare the following property:
+static {
+ io.swagger.v3.core.jackson.ModelResolver.enumsAsRef = true;
+}
+You can set list of paths to include using the following property:
+springdoc.pathsToMatch=/v1, /api/balance/**+
You can set list of packages to include using the following property:
+springdoc.packagesToScan=package1, package2+
These can be set by creating a swaggerUiConfig bean as follows:
@Bean
+@Primary
+fun swaggerUiConfig(config: SwaggerUiConfigProperties): SwaggerUiConfigProperties {
+ config.showCommonExtensions = true
+ config.queryConfigEnabled = true
+ return config
+}
+You can use the following annotation on the top of the field that you want to hide:
+@Schema(hidden = true)
@AuthenticationPrincipal parameter from spring-security ?A solution workaround would be to use: @Parameter(hidden = true)
The projects that use spring-boot-starter-security or spring-security-oauth2-authorization-server should use:
springdoc-openapi-starter-webmvc-api if they depend on spring-boot-starter-web and they only need the access to the OpenAPI endpoints.
OR springdoc-openapi-starter-webmvc-ui, if they depend on spring-boot-starter-web and they also need the access to the swagger-ui.
OR springdoc-openapi-starter-webflux-api if they depend on spring-boot-starter-webflux and they only the access to the OpenAPI endpoints.
OR springdoc-openapi-starter-webflux-ui, if they depend on spring-boot-starter-webflux and they also need the access to the swagger-ui.
Yes. More details are available, in the gradle plugin section.
+You can use @Parameter(hidden = true)
springdoc-openapi support Jersey?If you are using JAX-RS and as implementation Jersey (@Path for example), we do not support it.
We only support exposing Rest Endpoints using Spring managed beans (@RestController for example).
You can have a look at swagger-jaxrs2 project:
+ +springdoc-openapi generate API only for @RestController?@RestController is equivalent to @Controller + @RequestMapping on the type level.
For some legacy apps, we are constrained to still support both.
+If you need to hide the @Controller on the type level, in this case, you can use: @Hidden on controller level.
Please note this annotation can be also used to hide some methods from the generated documentation.
+@NotEmpty @NotBlank @PositiveOrZero @NegativeOrZero?Yes
+Pageable (spring-data-commons) object to correct URL-Parameter in Swagger UI?The support for Pageable of spring-data-commons is available out-of-the box since springdoc-openapi v1.6.0.
+For this, you have to combine @ParameterObject annotation with the Pageable type.
Before springdoc-openapi v1.6.0:
You can use as well @ParameterObject instead of @PageableAsQueryParam for HTTP GET methods.
static {
+ getConfig().replaceParameterObjectWithClass(org.springframework.data.domain.Pageable.class, Pageable.class)
+ .replaceParameterObjectWithClass(org.springframework.data.domain.PageRequest.class, Pageable.class);
+}
+Another solution, is to configure Pageable manually:
+you will have to declare the explicit mapping of Pageable fields as Query Params and add the @Parameter(hidden = true) Pageable pageable on your pageable parameter.
You should also, declare the annotation @PageableAsQueryParam provided by springdoc-openapi on the method level, or declare your own if need to define your custom description, defaultValue, …
If you want to disable the support of spring Pageable Type, you can use:
+springdoc.model-converters.pageable-converter.enabled=false| + + | +
+The property springdoc.model-converters.pageable-converter.enabled is only available since v1.5.11+
+ |
+
You could add a property allowableValues, to @Parameter. For example:
@GetMapping("/example")
+public Object example(@Parameter(name ="json", schema = @Schema(description = "var 1",type = "string", allowableValues = {"1", "2"}))
+String json) {
+ return null;
+}
+or you could override toString on your enum:
@Override
+@JsonValue
+public String toString() {
+ return String.valueOf(action);
+}
+springdoc-openapi-starter-webmvc-ui behind a reverse proxy?If your application is running behind a proxy, a load-balancer or in the cloud, the request information (like the host, port, scheme…) might change along the way. Your application may be running on 10.10.10.10:8080, but HTTP clients should only see example.org.
RFC7239 "Forwarded Headers" defines the Forwarded HTTP header; proxies can use this header to provide information about the original request. You can configure your application to read those headers and automatically use that information when creating links and sending them to clients in HTTP 302 responses, JSON documents or HTML pages. There are also non-standard headers, like X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Proto, X-Forwarded-Ssl, and X-Forwarded-Prefix.
If the proxy adds the commonly used X-Forwarded-For and X-Forwarded-Proto headers, setting server.forward-headers-strategy to NATIVE is enough to support those. With this option, the Web servers themselves natively support this feature; you can check their specific documentation to learn about specific behavior.
You need to make sure the following header is set in your reverse proxy configuration: X-Forwarded-Prefix
For example, using Apache 2, configuration:
+RequestHeader set X-Forwarded-Prefix "/custom-path"+
Then, in your Spring Boot application make sure your application handles this header: X-Forwarded-For. There are two ways to achieve this:
server.use-forward-headers=true+
If this is not enough, Spring Framework provides a ForwardedHeaderFilter. You can register it as a Servlet Filter in your application by setting server.forward-headers-strategy is set to FRAMEWORK.
Since Spring Boot 2.2, this is the new property to handle reverse proxy headers:
+server.forward-headers-strategy=frameworkAnd you can add the following bean to your application:
+@Bean
+ForwardedHeaderFilter forwardedHeaderFilter() {
+ return new ForwardedHeaderFilter();
+}
+If you need to manually adjust the URL displayed in the Swagger UI, implement the ServerBaseUrlCustomizer interface. This might be necessary to remove the port number, for example.
@Bean
+public class CustomServerBaseUrlCustomizer implements ServerBaseUrlCustomizer {
+ @Override
+ public String customize(String serverBaseUrl) {
+ try {
+ URL url = new URL(serverBaseUrl);
+ if (url.getHost().contains(".com")) {
+ serverBaseUrl = new URL(url.getProtocol(),url.getHost(),url.getFile()).toString();
+ }
+ } catch (MalformedURLException ex) {
+ // nothing we can do
+ }
+
+ return serverBaseUrl;
+ }
+}
+springdoc-openapi-starter-webmvc-ui dependency breaks my public/index.html welcome pageIf you already have static content on your root, and you don’t want it to be overridden by springdoc-openapi-starter-webmvc-ui configuration, you can just define a custom configuration of the swagger-ui, in order not to override the configuration of your files from in your context-root:
For example use:
+springdoc.swagger-ui.path= /swagger-ui/api-docs.html+
You can have a look on this sample test of the UI:
+ +You can write your own implementation of OpenApiCustomizer.
An example is available on:
+ +@Bean
+public OpenApiCustomizer consumerTypeHeaderOpenAPICustomizer() {
+return openApi -> openApi.getPaths().values().stream().flatMap(pathItem -> pathItem.readOperations().stream())
+ .forEach(operation -> operation.addParametersItem(new HeaderParameter().$ref("#/components/parameters/myConsumerTypeHeader")));
+}
+| + + | +
+This bean OpenApiCustomizer will be applied to the Default OpenAPI only.
+ |
+
If you need the OpenApiCustomizer to applied to GroupedOpenApi as well, then use GlobalOpenApiCustomizer instead.
It is be possible to handle as return an empty content as response using, one of the following syntaxes:
+content = @Content
content = @Content(schema = @Schema(hidden = true))
For example:
+@Operation(summary = "Get thing", responses = {
+ @ApiResponse(description = "Successful Operation", responseCode = "200", content = @Content(mediaType = "application/json", schema = @Schema(implementation = String.class))),
+ @ApiResponse(responseCode = "404", description = "Not found", content = @Content),
+ @ApiResponse(responseCode = "401", description = "Authentication Failure", content = @Content(schema = @Schema(hidden = true))) })
+@RequestMapping(path = "/testme", method = RequestMethod.GET)
+ResponseEntity<String> testme() {
+ return ResponseEntity.ok("Hello");
+}
+An overloaded method on the same class, with the same HTTP Method and path, will have as a result, only one OpenAPI Operation generated.
+In addition, it’s recommended to have the @Operation in the level of one of the overloaded methods. Otherwise it might be overridden if it’s declared many times within the same overloaded method.
You can use springdoc-openapi-maven-plugin for this functionality:
You can customise the output directory (property outputDir): The default value is: ${project.build.directory}
+Principal, Locale, HttpServletRequest and HttpServletResponse and other injectable parameters supported by Spring MVC are excluded.
Full documentation here:
+ +If you don’t want to ignore the types Principal, Locale, HttpServletRequest, and others,:
SpringDocUtils.getConfig().removeRequestWrapperToIgnore(HttpServletRequest.class)
+You should add the @SecurityRequirement tags to your protected APIs.
For example:
+@Operation(security = { @SecurityRequirement(name = "bearer-key") })
+And the security definition sample:
+@Bean
+ public OpenAPI customOpenAPI() {
+ return new OpenAPI()
+ .components(new Components()
+ .addSecuritySchemes("bearer-key",
+ new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")));
+}
+OAS 3 was released in July 2017, and there was no release of springfox to support OAS 3.
+springfox covers for the moment only swagger 2 integration with Spring Boot. The latest release date is June 2018. So, in terms of maintenance there is a big lack of support lately.
We decided to move forward and share the library that we already used on our internal projects, with the community.
+The biggest difference with springfox, is that we integrate new features not covered by springfox:
The integration between Spring Boot and OpenAPI 3 standard.
+We rely on on swagger-annotations and swagger-ui only official libraries.
We support new features on Spring 5, like spring-webflux with annotated and functional style.
We do our best to answer all the questions and address all issues or enhancement requests
+There is no relation between springdoc-openapi and springfox.If you want to migrate to OpenAPI 3:
Remove all the dependencies and the related code to springfox
+Add springdoc-openapi-starter-webmvc-ui dependency
If you don’t want to serve the UI from your root path or there is a conflict with an existing configuration, you can just change the following property:
+springdoc.swagger-ui.path=/you-path/swagger-ui.html+
You may have global parameters with Standard OpenAPI description.
+If you need the definitions to appear globally (within every group), no matter if the group fulfills the conditions specified on the GroupedOpenApi , you can use OpenAPI Bean.
+You can define common parameters under parameters in the global components section and reference them elsewhere via $ref. You can also define global header parameters.
For this, you can override to OpenAPI Bean, and set the global headers or parameters definition on the components level.
+@Bean
+public OpenAPI customOpenAPI(@Value("${springdoc.version}") String appVersion) {
+ return new OpenAPI()
+ .components(new Components().addSecuritySchemes("basicScheme", new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic"))
+ .addParameters("myHeader1", new Parameter().in("header").schema(new StringSchema()).name("myHeader1")).addHeaders("myHeader2", new Header().description("myHeader2 header").schema(new StringSchema())))
+ .info(new Info()
+ .title("Petstore API")
+ .version(appVersion)
+ .description("This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.")
+ .termsOfService("http://swagger.io/terms/")
+ .license(new License().name("Apache 2.0").url("http://springdoc.org")));
+}
+You can use: @SecurityScheme annotation.
Or you can define it programmatically, by overriding OpenAPI Bean:
+ @Bean
+ public OpenAPI customOpenAPI(@Value("${springdoc.version}") String appVersion) {
+ return new OpenAPI()
+ .components(new Components().addSecuritySchemes("basicScheme",
+ new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic")))
+ info(new Info().title("SpringShop API").version(appVersion)
+ .license(new License().name("Apache 2.0").url("http://springdoc.org")));
+ }
+You can use @io.swagger.v3.oas.annotations.Hidden annotation at @RestController, @RestControllerAdvice and method level
The @Hidden annotation on exception handler methods, is considered when building generic (error) responses from @ControllerAdvice exception handlers.
Or use: @Operation(hidden = true)
For global SecurityScheme, you can add it inside your own OpenAPI definition:
+@Bean
+public OpenAPI customOpenAPI() {
+ return new OpenAPI().components(new Components()
+ .addSecuritySchemes("basicScheme", new SecurityScheme()
+ .type(SecurityScheme.Type.HTTP).scheme("basic"))).info(new Info().title("Custom API")
+ .version("100")).addTagsItem(new Tag().name("mytag"));
+}
+The support of spring property resolver for @Info: title * description * version * termsOfService
The support of spring property resolver for @Info.license: name * url
The support of spring property resolver for @Info.contact: name * email * url
The support of spring property resolver for @Operation: description * summary
The support of spring property resolver for @Parameter: description * name
The support of spring property resolver for @ApiResponse: description
Its also possible to declare security URLs for @OAuthFlow: openIdConnectUrl * authorizationUrl * refreshUrl * tokenUrl
The support of spring property resolver for @Schema: name * title * description , by setting springdoc.api-docs.resolve-schema-properties to true
The support of spring property resolver for @ExtensionProperty by setting springdoc.api-docs.resolve-extensions-properties to true
Generating automatically server URL may be useful, if the documentation is not present.
+If the server annotations are present, they will be used instead.
+By default, the OpenAPI description is calculated once, and then cached.
+Sometimes the same swagger-ui is served behind internal and external proxies. some users want the server URL, to be computed on each http request.
+In order to disable springdoc cache, you will have to set the following property:
+springdoc.cache.disabled= true+
swagger-ui?You should use the springdoc-openapi-core dependency only:
<dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
+ <version>latest.version</version>
+</dependency>springdoc-openapi endpoints ?Use the following property:
+springdoc.api-docs.enabled=false+
To hide the response element, using @Schema annotation, as follows, at operation level:
@Operation(responses = @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(hidden = true))))+
Or directly at @ApiResponses level:
@ApiResponses(value = {@ApiResponse(responseCode = "200", content = @Content(schema = @Schema(hidden = true))) })
+OR
+@ApiResponse(responseCode = "404", description = "Not found", content = @Content)
+swagger-ui, when I set a different context-path?If you use different context-path:
+server.servlet.context-path= /foo+
The swagger-ui will be available on the following URL:
http://server:port/foo/swagger-ui.html
You can Define your own OpenAPI Bean: If you need the definitions to appear globally (within every group), no matter if the group fulfills the conditions specified on the GroupedOpenApi , you can use OpenAPI Bean.
+@Bean
+public OpenAPI customOpenAPI(@Value("${springdoc.version}") String appVersion) {
+ return new OpenAPI()
+ .components(new Components().addSecuritySchemes("basicScheme",
+ new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic")))
+ .info(new Info().title("SpringShop API").version(appVersion)
+ .license(new License().name("Apache 2.0").url("http://springdoc.org")));
+}
+If you need the definitions to appear within a specific group, and respect the conditions specified on the GroupedOpenApi, you can add OpenApiCustomizer to your GroupedOpenApi definition.
+GroupedOpenApi.builder().group("users").pathsToMatch(paths).packagesToScan(packagedToMatch).addOpenApiCustomizer(customerGlobalHeaderOpenApiCustomizer())
+ .build()
+
+@Bean
+public OpenApiCustomizer customerGlobalHeaderOpenApiCustomizer() {
+ return openApi -> openApi.path("/foo",
+ new PathItem().get(new Operation().operationId("foo").responses(new ApiResponses()
+ .addApiResponse("default",new ApiResponse().description("")
+ .content(new Content().addMediaType("fatz", new MediaType()))))));
+}
+The source code of the application is available at the following GitHub repository:
+ +The library supports the main file types: MultipartFile, @RequestPart, FilePart
You can upload a file as follows:
+@PostMapping(value = "/upload", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
+public ResponseEntity<?> upload(@Parameter(description = "file") final MultipartFile file) {
+ return null;
+}
+
+@PostMapping(value = "/uploadFileWithQuery", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
+public ResponseEntity<?> uploadFileWithQuery(@Parameter(description = "file") @RequestPart("file") final MultipartFile file,
+ @Parameter(description = "An extra query parameter") @RequestParam String name) {
+ return null;
+}
+
+@PostMapping(value = "/uploadFileWithJson", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE}, produces = {
+ MediaType.APPLICATION_JSON_VALUE})
+public ResponseEntity<?> uploadFileWithJson(
+ @RequestBody(content = @Content(encoding = @Encoding(name = "jsonRequest", contentType = MediaType.APPLICATION_JSON_VALUE)))
+ @Parameter(description = "An extra JSON payload sent with file") @RequestPart("jsonRequest") final JsonRequest jsonRequest,
+ @RequestPart("file") final MultipartFile file) {
+ return null;
+}
+Any @GetMapping parameters is marked as required, even if @RequestParam is missing.
You can add @Parameter(required=false) annotation if you need different behaviour.
Query parameters with defaultValue specified are marked as required.
springdoc-openapi renders these methods as a single endpoint. It detects the overloaded endpoints, and generates parameters.schema.oneOf.
With this property, all the springdoc-openapi auto-configuration beans are disabled:
springdoc.api-docs.enabled=false+
Then enable the minimal Beans configuration, by adding this Bean:
+@Bean
+SpringDocConfiguration springDocConfiguration(){
+ return new SpringDocConfiguration();
+}
+
+@Bean
+SpringDocConfigProperties springDocConfigProperties() {
+ return new SpringDocConfigProperties();
+}
+
+@Bean
+ObjectMapperProvider objectMapperProvider(SpringDocConfigProperties springDocConfigProperties){
+ return new ObjectMapperProvider(springDocConfigProperties);
+}
+Then configure, the path of your custom UI yaml file.
+springdoc.swagger-ui.url=/api-docs.yaml+
The OpenAPI 3 specification does not allow explicitly adding Authorization header.
+Note: Header parameters named Accept, Content-Type and Authorization are not allowed. To describe these headers
For more information, you can read:
+ +This is the default behaviour if your @Controller doesn’t have annotation @ResponseBody
You can change your controllers to @RestControllers. Or add @ResponseBody + @Controller.
If its not possible, you can configure springdoc to scan you additional controller using SpringDocUtils. For example:
+static {
+ SpringDocUtils.getConfig().addRestControllers(HelloController.class);
+}
+You can load groups dynamically using spring-boot configuration files.
+Note that, for this usage, you don’t have to declare the GroupedOpenApi Bean.
+You need to declare the following properties, under the prefix springdoc.group-configs.
+For example:
+springdoc.group-configs[0].group=users +springdoc.group-configs[0].paths-to-match=/user/** +springdoc.group-configs[0].packages-to-scan=test.org.springdoc.api+
The list of properties under this prefix, are available here:
+You can use springdoc annotation @ParameterObject.
+Request parameter annotated with @ParameterObject will help adding each field of the parameter as a separate request parameter.
+This is compatible with Spring MVC request parameters mapping to POJO object.
+This annotation does not support nested parameter objects.
+POJO object must contain getters for fields with mandatory prefix get. Otherwise, the swagger documentation will not show the fields of the annotated entity.
springdoc-openapi SNAPSHOT ?For testing purposes only, you can test temporarily using the last springdoc-openapi SNAPSHOT
To achieve that, configure your pom.xml file with the following <repositories> section:
<repositories>
+ <repository>
+ <name>Central Portal Snapshots</name>
+ <id>central-portal-snapshots</id>
+ <url>https://central.sonatype.com/repository/maven-snapshots/</url>
+ <releases>
+ <enabled>false</enabled>
+ </releases>
+ <snapshots>
+ <enabled>true</enabled>
+ </snapshots>
+ </repository>
+ </repositories>springdoc-openapi MonetaryAmount support ?If an application wants to enable the springdoc-openapi support, it declares:
SpringDocUtils.getConfig().replaceWithClass(MonetaryAmount.class, org.springdoc.core.converters.models.MonetaryAmount.class);
+Another solution, without using springdoc-openapi MonetaryAmount, would be:
+SpringDocUtils.getConfig().replaceWithSchema(MonetaryAmount.class, new ObjectSchema()
+ .addProperties("amount", new NumberSchema()).example(99.96)
+ .addProperties("currency", new StringSchema().example("USD")));
+The properties springdoc.swagger-ui.urls.*, are suitable to configure external (/v3/api-docs url).
+For example if you want to agreagte all the endpoints of other services, inside one single application.
+IMPORTANT: Don’t forget that CORS needs to be enabled as well.
If your file open-api.json, contains the OpenAPI documentation in OpenAPI 3 format. +Then simply declare: The file name can be anything you want, from the moment your declaration is consistent yaml or json OpenAPI Spec.
+ springdoc.swagger-ui.url=/open-api.jsonThen the file open-api.json, should be located in: src/main/resources/static +No additional configuration is needed.
+If you are using standard headers.( For example using spring-security headers) +If the CSRF Token is required, swagger-ui automatically sends the new XSRF-TOKEN during each HTTP REQUEST.
+If your XSRF-TOKEN isn’t standards-based, you can use a requestInterceptor to manually capture and attach the latest xsrf token to requests programmatically via spring resource transformer:
+Starting from release v1.4.4 of springdoc-openapi, a new property is added to enable CSRF support, while using standard header names:
+springdoc.swagger-ui.csrf.enabled=trueYou can use the following property:
+springdoc.swagger-ui.disable-swagger-default-url=trueYes, you can use it in conjunction with @ParameterObject annotation.
+Also, the spring-boot spring.data.web. and spring.data.rest.default. properties are supported since v1.4.5
You can use the following property:
+springdoc.show-login-endpoint=trueYou can use the following property:
+springdoc.remove-broken-reference-definitions=falseThe whole idea of springdoc-openapi is to get your documentation the closest to the code, with minimal code changes.
+If the code contains @Deprecated, sprindoc-openapi will consider its schema as Deprecated as well.
+If you want to declare a field on swagger as non deprecated, even with the java code, the field contains @Depreacted,
+You can use the following property that is available since release v1.4.3:
springdoc.model-converters.deprecating-converter.enabled=falseYou can use the following property:
+springdoc.model-and-view-allowed=trueYou can use the following property:
+springdoc.writer-with-default-pretty-printer=trueComplex objects are always resolved as a reference to a schema defined in components.
+For example let’s consider a Instance class with an workAddress and homeAddress attribute of type Address:
public class PersonDTO {
+
+ @JsonProperty
+ private String email;
+
+ @JsonProperty
+ private String firstName;
+
+ @JsonProperty
+ private String lastName;
+
+ @Schema(ref = "WorkAddressSchema")
+ @JsonProperty
+ private Address workAddress;
+
+ @Schema(ref = "HomeAddressSchema")
+ @JsonProperty
+ private Address homeAddress;
+
+}
+
+public class Address {
+
+ @JsonProperty
+ private String addressName;
+
+}
+If you want to define two different schemas for this class, you can set up 2 different schemas as follow:
+@Bean
+public OpenAPI customOpenAPI() {
+return new OpenAPI().components(new Components()
+.addSchemas("WorkAddressSchema", getSchemaWithDifferentDescription(Address.class, "work Address" ))
+.addSchemas("HomeAddressSchema", getSchemaWithDifferentDescription(Address.class, "home Address" )));
+}
+
+private Schema getSchemaWithDifferentDescription(Class className, String description){
+ResolvedSchema resolvedSchema = ModelConverters.getInstance()
+.resolveAsResolvedSchema(
+new AnnotatedType(className).resolveAsRef(false));
+return resolvedSchema.schema.description(description);
+}
+For example let’s consider a Instance class with an email attribute:
public class PersonDTO {
+
+ @JsonProperty
+ private String email;
+
+ @JsonProperty
+ private String firstName;
+
+ @JsonProperty
+ private String lastName;
+
+
+}
+If you want to define two different description for the email, you can set up 2 different schemas as follow:
@Bean
+public OpenAPI customOpenAPI() {
+return new OpenAPI().components(new Components()
+.addSchemas("PersonDTO1", getFieldSchemaWithDifferentDescription(PersonDTO.class, "work email" ))
+.addSchemas("PersonDTO2", getFieldSchemaWithDifferentDescription(PersonDTO.class, "home email" )));
+}
+
+private Schema getFieldSchemaWithDifferentDescription(Class className, String description){
+ ResolvedSchema resolvedSchema = ModelConverters.getInstance()
+ .resolveAsResolvedSchema(
+ new AnnotatedType(className).resolveAsRef(false));
+ return resolvedSchema.schema.addProperties("email", new StringSchema().description(description));
+}
+You can customize swagger documentation static resources located in META-INF/resources/webjars/swagger-ui/{swagger.version}/. The list of resources includes:
index.html
swagger-ui-bundle.js
swagger-ui.css
swagger-ui-standalone-preset.js
swagger-ui.css.map
swagger-ui-bundle.js.map
swagger-ui-standalone-preset.js.map
favicon-32x32.png
To do this, you need to extend the implementation of SwaggerIndexPageTransformer
public class SwaggerCodeBlockTransformer
+ extends SwaggerIndexPageTransformer {
+ // < constructor >
+ @Override
+ public Resource transform(HttpServletRequest request,
+ Resource resource,
+ ResourceTransformerChain transformer)
+ throws IOException {
+ if (resource.toString().contains("swagger-ui.css")) {
+ final InputStream is = resource.getInputStream();
+ final InputStreamReader isr = new InputStreamReader(is);
+ try (BufferedReader br = new BufferedReader(isr)) {
+ final String css = br.lines().collect(Collectors.joining());
+ final byte[] transformedContent = css.replace("old", "new").getBytes();
+ return new TransformedResource(resource, transformedContent);
+ } // AutoCloseable br > isr > is
+ }
+ return super.transform(request, resource, transformer);
+ }
+
+}
+Next, add transformer @Bean to your @Configuration
@Configuration
+public class OpenApiConfig {
+ @Bean
+ public SwaggerIndexTransformer swaggerIndexTransformer(
+ SwaggerUiConfigProperties a,
+ SwaggerUiOAuthProperties b,
+ SwaggerUiConfigParameters c,
+ SwaggerWelcomeCommon d) {
+ return new SwaggerCodeBlockTransformer(a, b, c, d);
+ }
+}
+Illustrative example
+
+The native support available added in spring-boot 3. +If you have some time, do not hesitate to test it before the next release.
+For the OpenAPI REST endpoints, you just need to build your application with the spring native profile.
If you give @OpenAPIDefinition or @SecurityScheme to a class that has no implementation, that class will disappear when you natively compile.
+To avoid this, give the class a @Configuration.
@Configuration
+@OpenAPIDefinition(info = @Info(title = "My App", description = "description"))
+public class OpenAPIConfig {
+}
+When your application is using spring without (spring-boot), you need to add beans and auto-configuration that are natively provided in spring-boot.
+For example, lets assume you want load the swagger-ui in spring-mvc application:
+You mainly, need to add the springdoc-openapi module
+<dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+ <version>last.version</version>
+</dependency>If you don’t have the spring-boot and spring-boot-autoconfigure dependencies, you need to add them. And pay attention to the compatibility matrix, between you spring.version and spring-boot.version. For example, in this case (spring.version=5.1.12.RELEASE):
+ <dependency>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-autoconfigure</artifactId>
+ <version>3.3.3</version>
+ </dependency>Scan for the springdoc-openapi 'auto-configuration classes that spring-boot automatically loads for you.
Depending on your module, you can find them on the file: spring.factories of each springdoc-openapi module.
@Configuration
+@EnableWebMvc
+public class WebConfig implements WebApplicationInitializer {
+
+ @Override
+ public void onStartup(ServletContext servletContext) {
+ WebApplicationContext context = getContext();
+ servletContext.addListener(new ContextLoaderListener(context));
+ ServletRegistration.Dynamic dispatcher = servletContext.addServlet("RestServlet",
+ new DispatcherServlet(context));
+ dispatcher.setLoadOnStartup(1);
+ dispatcher.addMapping("/*");
+ }
+
+ private AnnotationConfigWebApplicationContext getContext() {
+ AnnotationConfigWebApplicationContext context = new AnnotationConfigWebApplicationContext();
+ context.register(this.getClass(),
+ SpringDocConfiguration.class,
+ SpringDocConfigProperties.class,
+ SpringDocSpecPropertiesConfiguration.class,
+ SpringDocWebMvcConfiguration.class,
+ MultipleOpenApiSupportConfiguration.class,
+ SwaggerConfig.class,
+ SwaggerUiConfigProperties.class,
+ SwaggerUiOAuthProperties.class,
+ );
+ return context;
+ }
+}
+Depending on your module, you can find them on the file: org.springframework.boot.autoconfigure.AutoConfiguration.imports of each springdoc-openapi module.
For groups usage make sure your GroupedOpenApi Beans are scanned.
If additionally, you are using custom context path: /my-servlet-path. Make sure you declare the following property:
spring.mvc.servlet.path=/my-servlet-path+
springdoc-openapi with spring-boot ?springdoc-openapi 2.x is compatible with spring-boot 3.
In general, you should only pick the last stable version as per today 2.8.9.
+More precisely, this the exhaustive list of spring-boot versions against which springdoc-openapi has been built:
Spring Boot Versions |
+Springdoc OpenAPI Versions |
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
Swagger UI unable to render definition, when overriding the default spring registered HttpMessageConverter?When overriding the default spring-boot registered HttpMessageConverter, you should have ByteArrayHttpMessageConverter registered as well to have proper springdoc-openapi support.
converters.add(new ByteArrayHttpMessageConverter());
+ converters.add(new MappingJackson2HttpMessageConverter(jacksonBuilder.build()));
+| + + | +
+Order is very important, when registering HttpMessageConverters.
+ |
+
The issue is caused by the changes introduced by Spring-Boot 3.2.0
+in particular for the Parameter Name Discovery.
+This can be fixed by adding the -parameters arg to the Maven Compiler Plugin.
<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <parameters>true</parameters>
+ </configuration>
+</plugin>springdoc-openapi java library helps to automate the generation of API documentation using spring boot projects.
+springdoc-openapi works by examining an application at runtime to infer API semantics based on spring configurations, class structure and various annotations.
Automatically generates documentation in JSON/YAML and HTML format APIs. +This documentation can be completed by comments using swagger-api annotations.
+This library supports:
+OpenAPI 3
+Spring-boot v3 (Java 17 & Jakarta EE 9)
+JSR-303, specifically for @NotNull, @Min, @Max, and @Size.
+Swagger-ui
+OAuth 2
+GraalVM native images
+The following video introduces the Library:
+
+This is a community-based project, not maintained by the Spring Framework Contributors (Pivotal).
+ blocks on a page\n *\n * @type {Function & {called?: boolean}}\n */\n // TODO: remove v12, deprecated\n const initHighlighting = () => {\n if (initHighlighting.called) return;\n initHighlighting.called = true;\n\n deprecated(\"10.6.0\", \"initHighlighting() is deprecated. Use highlightAll() instead.\");\n\n const blocks = document.querySelectorAll('pre code');\n blocks.forEach(highlightElement);\n };\n\n // Higlights all when DOMContentLoaded fires\n // TODO: remove v12, deprecated\n function initHighlightingOnLoad() {\n deprecated(\"10.6.0\", \"initHighlightingOnLoad() is deprecated. Use highlightAll() instead.\");\n wantsHighlight = true;\n }\n\n let wantsHighlight = false;\n\n /**\n * auto-highlights all pre>code elements on the page\n */\n function highlightAll() {\n // if we are called too early in the loading process\n if (document.readyState === \"loading\") {\n wantsHighlight = true;\n return;\n }\n\n const blocks = document.querySelectorAll('pre code');\n blocks.forEach(highlightElement);\n }\n\n function boot() {\n // if a highlight was requested before DOM was loaded, do now\n if (wantsHighlight) highlightAll();\n }\n\n // make sure we are in the browser environment\n if (typeof window !== 'undefined' && window.addEventListener) {\n window.addEventListener('DOMContentLoaded', boot, false);\n }\n\n /**\n * Register a language grammar module\n *\n * @param {string} languageName\n * @param {LanguageFn} languageDefinition\n */\n function registerLanguage(languageName, languageDefinition) {\n let lang = null;\n try {\n lang = languageDefinition(hljs);\n } catch (error$1) {\n error(\"Language definition for '{}' could not be registered.\".replace(\"{}\", languageName));\n // hard or soft error\n if (!SAFE_MODE) { throw error$1; } else { error(error$1); }\n // languages that have serious errors are replaced with essentially a\n // \"plaintext\" stand-in so that the code blocks will still get normal\n // css classes applied to them - and one bad language won't break the\n // entire highlighter\n lang = PLAINTEXT_LANGUAGE;\n }\n // give it a temporary name if it doesn't have one in the meta-data\n if (!lang.name) lang.name = languageName;\n languages[languageName] = lang;\n lang.rawDefinition = languageDefinition.bind(null, hljs);\n\n if (lang.aliases) {\n registerAliases(lang.aliases, { languageName });\n }\n }\n\n /**\n * Remove a language grammar module\n *\n * @param {string} languageName\n */\n function unregisterLanguage(languageName) {\n delete languages[languageName];\n for (const alias of Object.keys(aliases)) {\n if (aliases[alias] === languageName) {\n delete aliases[alias];\n }\n }\n }\n\n /**\n * @returns {string[]} List of language internal names\n */\n function listLanguages() {\n return Object.keys(languages);\n }\n\n /**\n intended usage: When one language truly requires another\n\n Unlike `getLanguage`, this will throw when the requested language\n is not available.\n\n @param {string} name - name of the language to fetch/require\n @returns {Language | never}\n */\n function requireLanguage(name) {\n deprecated(\"10.4.0\", \"requireLanguage will be removed entirely in v11.\");\n deprecated(\"10.4.0\", \"Please see https://github.com/highlightjs/highlight.js/pull/2844\");\n\n const lang = getLanguage(name);\n if (lang) { return lang; }\n\n const err = new Error('The \\'{}\\' language is required, but not loaded.'.replace('{}', name));\n throw err;\n }\n\n /**\n * @param {string} name - name of the language to retrieve\n * @returns {Language | undefined}\n */\n function getLanguage(name) {\n name = (name || '').toLowerCase();\n return languages[name] || languages[aliases[name]];\n }\n\n /**\n *\n * @param {string|string[]} aliasList - single alias or list of aliases\n * @param {{languageName: string}} opts\n */\n function registerAliases(aliasList, { languageName }) {\n if (typeof aliasList === 'string') {\n aliasList = [aliasList];\n }\n aliasList.forEach(alias => { aliases[alias.toLowerCase()] = languageName; });\n }\n\n /**\n * Determines if a given language has auto-detection enabled\n * @param {string} name - name of the language\n */\n function autoDetection(name) {\n const lang = getLanguage(name);\n return lang && !lang.disableAutodetect;\n }\n\n /**\n * Upgrades the old highlightBlock plugins to the new\n * highlightElement API\n * @param {HLJSPlugin} plugin\n */\n function upgradePluginAPI(plugin) {\n // TODO: remove with v12\n if (plugin[\"before:highlightBlock\"] && !plugin[\"before:highlightElement\"]) {\n plugin[\"before:highlightElement\"] = (data) => {\n plugin[\"before:highlightBlock\"](\n Object.assign({ block: data.el }, data)\n );\n };\n }\n if (plugin[\"after:highlightBlock\"] && !plugin[\"after:highlightElement\"]) {\n plugin[\"after:highlightElement\"] = (data) => {\n plugin[\"after:highlightBlock\"](\n Object.assign({ block: data.el }, data)\n );\n };\n }\n }\n\n /**\n * @param {HLJSPlugin} plugin\n */\n function addPlugin(plugin) {\n upgradePluginAPI(plugin);\n plugins.push(plugin);\n }\n\n /**\n *\n * @param {PluginEvent} event\n * @param {any} args\n */\n function fire(event, args) {\n const cb = event;\n plugins.forEach(function(plugin) {\n if (plugin[cb]) {\n plugin[cb](args);\n }\n });\n }\n\n /**\n Note: fixMarkup is deprecated and will be removed entirely in v11\n\n @param {string} arg\n @returns {string}\n */\n function deprecateFixMarkup(arg) {\n deprecated(\"10.2.0\", \"fixMarkup will be removed entirely in v11.0\");\n deprecated(\"10.2.0\", \"Please see https://github.com/highlightjs/highlight.js/issues/2534\");\n\n return fixMarkup(arg);\n }\n\n /**\n *\n * @param {HighlightedHTMLElement} el\n */\n function deprecateHighlightBlock(el) {\n deprecated(\"10.7.0\", \"highlightBlock will be removed entirely in v12.0\");\n deprecated(\"10.7.0\", \"Please use highlightElement now.\");\n\n return highlightElement(el);\n }\n\n /* Interface definition */\n Object.assign(hljs, {\n highlight,\n highlightAuto,\n highlightAll,\n fixMarkup: deprecateFixMarkup,\n highlightElement,\n // TODO: Remove with v12 API\n highlightBlock: deprecateHighlightBlock,\n configure,\n initHighlighting,\n initHighlightingOnLoad,\n registerLanguage,\n unregisterLanguage,\n listLanguages,\n getLanguage,\n registerAliases,\n requireLanguage,\n autoDetection,\n inherit: inherit$1,\n addPlugin,\n // plugins for frameworks\n vuePlugin: BuildVuePlugin(hljs).VuePlugin\n });\n\n hljs.debugMode = function() { SAFE_MODE = false; };\n hljs.safeMode = function() { SAFE_MODE = true; };\n hljs.versionString = version;\n\n for (const key in MODES) {\n // @ts-ignore\n if (typeof MODES[key] === \"object\") {\n // @ts-ignore\n deepFreezeEs6(MODES[key]);\n }\n }\n\n // merge all the modes/regexs into our main object\n Object.assign(hljs, MODES);\n\n // built-in plugins, likely to be moved out of core in the future\n hljs.addPlugin(brPlugin); // slated to be removed in v11\n hljs.addPlugin(mergeHTMLPlugin);\n hljs.addPlugin(tabReplacePlugin);\n return hljs;\n};\n\n// export an \"instance\" of the highlighter\nvar highlight = HLJS({});\n\nmodule.exports = highlight;\n","/*\n * Copyright 2021 the original author or authors.\n *\n * Licensed under the Apache License, Version 2.0 (the 'License');\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an 'AS IS' BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n(function () {\n 'use strict';\n\n const highlightJs = require('highlight.js/lib/core');\n\n highlightJs.registerLanguage('asciidoc', require('highlight.js/lib/languages/asciidoc'));\n highlightJs.registerLanguage('bash', require('highlight.js/lib/languages/bash'));\n highlightJs.registerLanguage('css', require('highlight.js/lib/languages/css'));\n highlightJs.registerLanguage('diff', require('highlight.js/lib/languages/diff'));\n highlightJs.registerLanguage('dockerfile', require('highlight.js/lib/languages/dockerfile'));\n highlightJs.registerLanguage('dos', require('highlight.js/lib/languages/dos'));\n highlightJs.registerLanguage('gradle', require('highlight.js/lib/languages/gradle'));\n highlightJs.registerLanguage('groovy', require('highlight.js/lib/languages/groovy'));\n highlightJs.registerLanguage('http', require('highlight.js/lib/languages/http'));\n highlightJs.registerLanguage('java', require('highlight.js/lib/languages/java'));\n highlightJs.registerLanguage('javascript',require('highlight.js/lib/languages/javascript'));\n highlightJs.registerLanguage('json', require('highlight.js/lib/languages/json'));\n highlightJs.registerLanguage('kotlin', require('highlight.js/lib/languages/kotlin'));\n highlightJs.registerLanguage('markdown', require('highlight.js/lib/languages/markdown'));\n highlightJs.registerLanguage('nix', require('highlight.js/lib/languages/nix'));\n highlightJs.registerLanguage('powershell', require('highlight.js/lib/languages/powershell'));\n highlightJs.registerLanguage('properties', require('highlight.js/lib/languages/properties'));\n highlightJs.registerLanguage('ruby', require('highlight.js/lib/languages/ruby'));\n highlightJs.registerLanguage('scala', require('highlight.js/lib/languages/scala'));\n highlightJs.registerLanguage('shell', require('highlight.js/lib/languages/shell'));\n highlightJs.registerLanguage('sql', require('highlight.js/lib/languages/sql'));\n highlightJs.registerLanguage('xml', require('highlight.js/lib/languages/xml'));\n highlightJs.registerLanguage('yaml', require('highlight.js/lib/languages/yaml'));\n\n highlightJs.configure({ignoreUnescapedHTML: true});\n\n for(const codeElement of document.querySelectorAll('pre.highlight > code')) {\n highlightJs.highlightBlock(codeElement);\n }\n\n})();\n","/**\n * @param {string} value\n * @returns {RegExp}\n * */\n\n/**\n * @param {RegExp | string } re\n * @returns {string}\n */\nfunction source(re) {\n if (!re) return null;\n if (typeof re === \"string\") return re;\n\n return re.source;\n}\n\n/**\n * @param {...(RegExp | string) } args\n * @returns {string}\n */\nfunction concat(...args) {\n const joined = args.map((x) => source(x)).join(\"\");\n return joined;\n}\n\n/*\nLanguage: AsciiDoc\nRequires: xml.js\nAuthor: Dan Allen \nWebsite: http://asciidoc.org\nDescription: A semantic, text-based document format that can be exported to HTML, DocBook and other backends.\nCategory: markup\n*/\n\n/** @type LanguageFn */\nfunction asciidoc(hljs) {\n const HORIZONTAL_RULE = {\n begin: '^\\'{3,}[ \\\\t]*$',\n relevance: 10\n };\n const ESCAPED_FORMATTING = [\n // escaped constrained formatting marks (i.e., \\* \\_ or \\`)\n {\n begin: /\\\\[*_`]/\n },\n // escaped unconstrained formatting marks (i.e., \\\\** \\\\__ or \\\\``)\n // must ignore until the next formatting marks\n // this rule might not be 100% compliant with Asciidoctor 2.0 but we are entering undefined behavior territory...\n {\n begin: /\\\\\\\\\\*{2}[^\\n]*?\\*{2}/\n },\n {\n begin: /\\\\\\\\_{2}[^\\n]*_{2}/\n },\n {\n begin: /\\\\\\\\`{2}[^\\n]*`{2}/\n },\n // guard: constrained formatting mark may not be preceded by \":\", \";\" or\n // \"}\". match these so the constrained rule doesn't see them\n {\n begin: /[:;}][*_`](?![*_`])/\n }\n ];\n const STRONG = [\n // inline unconstrained strong (single line)\n {\n className: 'strong',\n begin: /\\*{2}([^\\n]+?)\\*{2}/\n },\n // inline unconstrained strong (multi-line)\n {\n className: 'strong',\n begin: concat(\n /\\*\\*/,\n /((\\*(?!\\*)|\\\\[^\\n]|[^*\\n\\\\])+\\n)+/,\n /(\\*(?!\\*)|\\\\[^\\n]|[^*\\n\\\\])*/,\n /\\*\\*/\n ),\n relevance: 0\n },\n // inline constrained strong (single line)\n {\n className: 'strong',\n // must not precede or follow a word character\n begin: /\\B\\*(\\S|\\S[^\\n]*?\\S)\\*(?!\\w)/\n },\n // inline constrained strong (multi-line)\n {\n className: 'strong',\n // must not precede or follow a word character\n begin: /\\*[^\\s]([^\\n]+\\n)+([^\\n]+)\\*/\n }\n ];\n const EMPHASIS = [\n // inline unconstrained emphasis (single line)\n {\n className: 'emphasis',\n begin: /_{2}([^\\n]+?)_{2}/\n },\n // inline unconstrained emphasis (multi-line)\n {\n className: 'emphasis',\n begin: concat(\n /__/,\n /((_(?!_)|\\\\[^\\n]|[^_\\n\\\\])+\\n)+/,\n /(_(?!_)|\\\\[^\\n]|[^_\\n\\\\])*/,\n /__/\n ),\n relevance: 0\n },\n // inline constrained emphasis (single line)\n {\n className: 'emphasis',\n // must not precede or follow a word character\n begin: /\\b_(\\S|\\S[^\\n]*?\\S)_(?!\\w)/\n },\n // inline constrained emphasis (multi-line)\n {\n className: 'emphasis',\n // must not precede or follow a word character\n begin: /_[^\\s]([^\\n]+\\n)+([^\\n]+)_/\n },\n // inline constrained emphasis using single quote (legacy)\n {\n className: 'emphasis',\n // must not follow a word character or be followed by a single quote or space\n begin: '\\\\B\\'(?![\\'\\\\s])',\n end: '(\\\\n{2}|\\')',\n // allow escaped single quote followed by word char\n contains: [{\n begin: '\\\\\\\\\\'\\\\w',\n relevance: 0\n }],\n relevance: 0\n }\n ];\n const ADMONITION = {\n className: 'symbol',\n begin: '^(NOTE|TIP|IMPORTANT|WARNING|CAUTION):\\\\s+',\n relevance: 10\n };\n const BULLET_LIST = {\n className: 'bullet',\n begin: '^(\\\\*+|-+|\\\\.+|[^\\\\n]+?::)\\\\s+'\n };\n\n return {\n name: 'AsciiDoc',\n aliases: ['adoc'],\n contains: [\n // block comment\n hljs.COMMENT(\n '^/{4,}\\\\n',\n '\\\\n/{4,}$',\n // can also be done as...\n // '^/{4,}$',\n // '^/{4,}$',\n {\n relevance: 10\n }\n ),\n // line comment\n hljs.COMMENT(\n '^//',\n '$',\n {\n relevance: 0\n }\n ),\n // title\n {\n className: 'title',\n begin: '^\\\\.\\\\w.*$'\n },\n // example, admonition & sidebar blocks\n {\n begin: '^[=\\\\*]{4,}\\\\n',\n end: '\\\\n^[=\\\\*]{4,}$',\n relevance: 10\n },\n // headings\n {\n className: 'section',\n relevance: 10,\n variants: [\n {\n begin: '^(={1,6})[ \\t].+?([ \\t]\\\\1)?$'\n },\n {\n begin: '^[^\\\\[\\\\]\\\\n]+?\\\\n[=\\\\-~\\\\^\\\\+]{2,}$'\n }\n ]\n },\n // document attributes\n {\n className: 'meta',\n begin: '^:.+?:',\n end: '\\\\s',\n excludeEnd: true,\n relevance: 10\n },\n // block attributes\n {\n className: 'meta',\n begin: '^\\\\[.+?\\\\]$',\n relevance: 0\n },\n // quoteblocks\n {\n className: 'quote',\n begin: '^_{4,}\\\\n',\n end: '\\\\n_{4,}$',\n relevance: 10\n },\n // listing and literal blocks\n {\n className: 'code',\n begin: '^[\\\\-\\\\.]{4,}\\\\n',\n end: '\\\\n[\\\\-\\\\.]{4,}$',\n relevance: 10\n },\n // passthrough blocks\n {\n begin: '^\\\\+{4,}\\\\n',\n end: '\\\\n\\\\+{4,}$',\n contains: [{\n begin: '<',\n end: '>',\n subLanguage: 'xml',\n relevance: 0\n }],\n relevance: 10\n },\n\n BULLET_LIST,\n ADMONITION,\n ...ESCAPED_FORMATTING,\n ...STRONG,\n ...EMPHASIS,\n\n // inline smart quotes\n {\n className: 'string',\n variants: [\n {\n begin: \"``.+?''\"\n },\n {\n begin: \"`.+?'\"\n }\n ]\n },\n // inline unconstrained emphasis\n {\n className: 'code',\n begin: /`{2}/,\n end: /(\\n{2}|`{2})/\n },\n // inline code snippets (TODO should get same treatment as strong and emphasis)\n {\n className: 'code',\n begin: '(`.+?`|\\\\+.+?\\\\+)',\n relevance: 0\n },\n // indented literal block\n {\n className: 'code',\n begin: '^[ \\\\t]',\n end: '$',\n relevance: 0\n },\n HORIZONTAL_RULE,\n // images and links\n {\n begin: '(link:)?(http|https|ftp|file|irc|image:?):\\\\S+?\\\\[[^[]*?\\\\]',\n returnBegin: true,\n contains: [\n {\n begin: '(link|image:?):',\n relevance: 0\n },\n {\n className: 'link',\n begin: '\\\\w',\n end: '[^\\\\[]+',\n relevance: 0\n },\n {\n className: 'string',\n begin: '\\\\[',\n end: '\\\\]',\n excludeBegin: true,\n excludeEnd: true,\n relevance: 0\n }\n ],\n relevance: 10\n }\n ]\n };\n}\n\nmodule.exports = asciidoc;\n","/**\n * @param {string} value\n * @returns {RegExp}\n * */\n\n/**\n * @param {RegExp | string } re\n * @returns {string}\n */\nfunction source(re) {\n if (!re) return null;\n if (typeof re === \"string\") return re;\n\n return re.source;\n}\n\n/**\n * @param {...(RegExp | string) } args\n * @returns {string}\n */\nfunction concat(...args) {\n const joined = args.map((x) => source(x)).join(\"\");\n return joined;\n}\n\n/*\nLanguage: Bash\nAuthor: vah \nContributrors: Benjamin Pannell \nWebsite: https://www.gnu.org/software/bash/\nCategory: common\n*/\n\n/** @type LanguageFn */\nfunction bash(hljs) {\n const VAR = {};\n const BRACED_VAR = {\n begin: /\\$\\{/,\n end:/\\}/,\n contains: [\n \"self\",\n {\n begin: /:-/,\n contains: [ VAR ]\n } // default values\n ]\n };\n Object.assign(VAR,{\n className: 'variable',\n variants: [\n {begin: concat(/\\$[\\w\\d#@][\\w\\d_]*/,\n // negative look-ahead tries to avoid matching patterns that are not\n // Perl at all like $ident$, @ident@, etc.\n `(?![\\\\w\\\\d])(?![$])`) },\n BRACED_VAR\n ]\n });\n\n const SUBST = {\n className: 'subst',\n begin: /\\$\\(/, end: /\\)/,\n contains: [hljs.BACKSLASH_ESCAPE]\n };\n const HERE_DOC = {\n begin: /<<-?\\s*(?=\\w+)/,\n starts: {\n contains: [\n hljs.END_SAME_AS_BEGIN({\n begin: /(\\w+)/,\n end: /(\\w+)/,\n className: 'string'\n })\n ]\n }\n };\n const QUOTE_STRING = {\n className: 'string',\n begin: /\"/, end: /\"/,\n contains: [\n hljs.BACKSLASH_ESCAPE,\n VAR,\n SUBST\n ]\n };\n SUBST.contains.push(QUOTE_STRING);\n const ESCAPED_QUOTE = {\n className: '',\n begin: /\\\\\"/\n\n };\n const APOS_STRING = {\n className: 'string',\n begin: /'/, end: /'/\n };\n const ARITHMETIC = {\n begin: /\\$\\(\\(/,\n end: /\\)\\)/,\n contains: [\n { begin: /\\d+#[0-9a-f]+/, className: \"number\" },\n hljs.NUMBER_MODE,\n VAR\n ]\n };\n const SH_LIKE_SHELLS = [\n \"fish\",\n \"bash\",\n \"zsh\",\n \"sh\",\n \"csh\",\n \"ksh\",\n \"tcsh\",\n \"dash\",\n \"scsh\",\n ];\n const KNOWN_SHEBANG = hljs.SHEBANG({\n binary: `(${SH_LIKE_SHELLS.join(\"|\")})`,\n relevance: 10\n });\n const FUNCTION = {\n className: 'function',\n begin: /\\w[\\w\\d_]*\\s*\\(\\s*\\)\\s*\\{/,\n returnBegin: true,\n contains: [hljs.inherit(hljs.TITLE_MODE, {begin: /\\w[\\w\\d_]*/})],\n relevance: 0\n };\n\n return {\n name: 'Bash',\n aliases: ['sh', 'zsh'],\n keywords: {\n $pattern: /\\b[a-z._-]+\\b/,\n keyword:\n 'if then else elif fi for while in do done case esac function',\n literal:\n 'true false',\n built_in:\n // Shell built-ins\n // http://www.gnu.org/software/bash/manual/html_node/Shell-Builtin-Commands.html\n 'break cd continue eval exec exit export getopts hash pwd readonly return shift test times ' +\n 'trap umask unset ' +\n // Bash built-ins\n 'alias bind builtin caller command declare echo enable help let local logout mapfile printf ' +\n 'read readarray source type typeset ulimit unalias ' +\n // Shell modifiers\n 'set shopt ' +\n // Zsh built-ins\n 'autoload bg bindkey bye cap chdir clone comparguments compcall compctl compdescribe compfiles ' +\n 'compgroups compquote comptags comptry compvalues dirs disable disown echotc echoti emulate ' +\n 'fc fg float functions getcap getln history integer jobs kill limit log noglob popd print ' +\n 'pushd pushln rehash sched setcap setopt stat suspend ttyctl unfunction unhash unlimit ' +\n 'unsetopt vared wait whence where which zcompile zformat zftp zle zmodload zparseopts zprof ' +\n 'zpty zregexparse zsocket zstyle ztcp'\n },\n contains: [\n KNOWN_SHEBANG, // to catch known shells and boost relevancy\n hljs.SHEBANG(), // to catch unknown shells but still highlight the shebang\n FUNCTION,\n ARITHMETIC,\n hljs.HASH_COMMENT_MODE,\n HERE_DOC,\n QUOTE_STRING,\n ESCAPED_QUOTE,\n APOS_STRING,\n VAR\n ]\n };\n}\n\nmodule.exports = bash;\n","const MODES = (hljs) => {\n return {\n IMPORTANT: {\n className: 'meta',\n begin: '!important'\n },\n HEXCOLOR: {\n className: 'number',\n begin: '#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})'\n },\n ATTRIBUTE_SELECTOR_MODE: {\n className: 'selector-attr',\n begin: /\\[/,\n end: /\\]/,\n illegal: '$',\n contains: [\n hljs.APOS_STRING_MODE,\n hljs.QUOTE_STRING_MODE\n ]\n }\n };\n};\n\nconst TAGS = [\n 'a',\n 'abbr',\n 'address',\n 'article',\n 'aside',\n 'audio',\n 'b',\n 'blockquote',\n 'body',\n 'button',\n 'canvas',\n 'caption',\n 'cite',\n 'code',\n 'dd',\n 'del',\n 'details',\n 'dfn',\n 'div',\n 'dl',\n 'dt',\n 'em',\n 'fieldset',\n 'figcaption',\n 'figure',\n 'footer',\n 'form',\n 'h1',\n 'h2',\n 'h3',\n 'h4',\n 'h5',\n 'h6',\n 'header',\n 'hgroup',\n 'html',\n 'i',\n 'iframe',\n 'img',\n 'input',\n 'ins',\n 'kbd',\n 'label',\n 'legend',\n 'li',\n 'main',\n 'mark',\n 'menu',\n 'nav',\n 'object',\n 'ol',\n 'p',\n 'q',\n 'quote',\n 'samp',\n 'section',\n 'span',\n 'strong',\n 'summary',\n 'sup',\n 'table',\n 'tbody',\n 'td',\n 'textarea',\n 'tfoot',\n 'th',\n 'thead',\n 'time',\n 'tr',\n 'ul',\n 'var',\n 'video'\n];\n\nconst MEDIA_FEATURES = [\n 'any-hover',\n 'any-pointer',\n 'aspect-ratio',\n 'color',\n 'color-gamut',\n 'color-index',\n 'device-aspect-ratio',\n 'device-height',\n 'device-width',\n 'display-mode',\n 'forced-colors',\n 'grid',\n 'height',\n 'hover',\n 'inverted-colors',\n 'monochrome',\n 'orientation',\n 'overflow-block',\n 'overflow-inline',\n 'pointer',\n 'prefers-color-scheme',\n 'prefers-contrast',\n 'prefers-reduced-motion',\n 'prefers-reduced-transparency',\n 'resolution',\n 'scan',\n 'scripting',\n 'update',\n 'width',\n // TODO: find a better solution?\n 'min-width',\n 'max-width',\n 'min-height',\n 'max-height'\n];\n\n// https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes\nconst PSEUDO_CLASSES = [\n 'active',\n 'any-link',\n 'blank',\n 'checked',\n 'current',\n 'default',\n 'defined',\n 'dir', // dir()\n 'disabled',\n 'drop',\n 'empty',\n 'enabled',\n 'first',\n 'first-child',\n 'first-of-type',\n 'fullscreen',\n 'future',\n 'focus',\n 'focus-visible',\n 'focus-within',\n 'has', // has()\n 'host', // host or host()\n 'host-context', // host-context()\n 'hover',\n 'indeterminate',\n 'in-range',\n 'invalid',\n 'is', // is()\n 'lang', // lang()\n 'last-child',\n 'last-of-type',\n 'left',\n 'link',\n 'local-link',\n 'not', // not()\n 'nth-child', // nth-child()\n 'nth-col', // nth-col()\n 'nth-last-child', // nth-last-child()\n 'nth-last-col', // nth-last-col()\n 'nth-last-of-type', //nth-last-of-type()\n 'nth-of-type', //nth-of-type()\n 'only-child',\n 'only-of-type',\n 'optional',\n 'out-of-range',\n 'past',\n 'placeholder-shown',\n 'read-only',\n 'read-write',\n 'required',\n 'right',\n 'root',\n 'scope',\n 'target',\n 'target-within',\n 'user-invalid',\n 'valid',\n 'visited',\n 'where' // where()\n];\n\n// https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-elements\nconst PSEUDO_ELEMENTS = [\n 'after',\n 'backdrop',\n 'before',\n 'cue',\n 'cue-region',\n 'first-letter',\n 'first-line',\n 'grammar-error',\n 'marker',\n 'part',\n 'placeholder',\n 'selection',\n 'slotted',\n 'spelling-error'\n];\n\nconst ATTRIBUTES = [\n 'align-content',\n 'align-items',\n 'align-self',\n 'animation',\n 'animation-delay',\n 'animation-direction',\n 'animation-duration',\n 'animation-fill-mode',\n 'animation-iteration-count',\n 'animation-name',\n 'animation-play-state',\n 'animation-timing-function',\n 'auto',\n 'backface-visibility',\n 'background',\n 'background-attachment',\n 'background-clip',\n 'background-color',\n 'background-image',\n 'background-origin',\n 'background-position',\n 'background-repeat',\n 'background-size',\n 'border',\n 'border-bottom',\n 'border-bottom-color',\n 'border-bottom-left-radius',\n 'border-bottom-right-radius',\n 'border-bottom-style',\n 'border-bottom-width',\n 'border-collapse',\n 'border-color',\n 'border-image',\n 'border-image-outset',\n 'border-image-repeat',\n 'border-image-slice',\n 'border-image-source',\n 'border-image-width',\n 'border-left',\n 'border-left-color',\n 'border-left-style',\n 'border-left-width',\n 'border-radius',\n 'border-right',\n 'border-right-color',\n 'border-right-style',\n 'border-right-width',\n 'border-spacing',\n 'border-style',\n 'border-top',\n 'border-top-color',\n 'border-top-left-radius',\n 'border-top-right-radius',\n 'border-top-style',\n 'border-top-width',\n 'border-width',\n 'bottom',\n 'box-decoration-break',\n 'box-shadow',\n 'box-sizing',\n 'break-after',\n 'break-before',\n 'break-inside',\n 'caption-side',\n 'clear',\n 'clip',\n 'clip-path',\n 'color',\n 'column-count',\n 'column-fill',\n 'column-gap',\n 'column-rule',\n 'column-rule-color',\n 'column-rule-style',\n 'column-rule-width',\n 'column-span',\n 'column-width',\n 'columns',\n 'content',\n 'counter-increment',\n 'counter-reset',\n 'cursor',\n 'direction',\n 'display',\n 'empty-cells',\n 'filter',\n 'flex',\n 'flex-basis',\n 'flex-direction',\n 'flex-flow',\n 'flex-grow',\n 'flex-shrink',\n 'flex-wrap',\n 'float',\n 'font',\n 'font-display',\n 'font-family',\n 'font-feature-settings',\n 'font-kerning',\n 'font-language-override',\n 'font-size',\n 'font-size-adjust',\n 'font-smoothing',\n 'font-stretch',\n 'font-style',\n 'font-variant',\n 'font-variant-ligatures',\n 'font-variation-settings',\n 'font-weight',\n 'height',\n 'hyphens',\n 'icon',\n 'image-orientation',\n 'image-rendering',\n 'image-resolution',\n 'ime-mode',\n 'inherit',\n 'initial',\n 'justify-content',\n 'left',\n 'letter-spacing',\n 'line-height',\n 'list-style',\n 'list-style-image',\n 'list-style-position',\n 'list-style-type',\n 'margin',\n 'margin-bottom',\n 'margin-left',\n 'margin-right',\n 'margin-top',\n 'marks',\n 'mask',\n 'max-height',\n 'max-width',\n 'min-height',\n 'min-width',\n 'nav-down',\n 'nav-index',\n 'nav-left',\n 'nav-right',\n 'nav-up',\n 'none',\n 'normal',\n 'object-fit',\n 'object-position',\n 'opacity',\n 'order',\n 'orphans',\n 'outline',\n 'outline-color',\n 'outline-offset',\n 'outline-style',\n 'outline-width',\n 'overflow',\n 'overflow-wrap',\n 'overflow-x',\n 'overflow-y',\n 'padding',\n 'padding-bottom',\n 'padding-left',\n 'padding-right',\n 'padding-top',\n 'page-break-after',\n 'page-break-before',\n 'page-break-inside',\n 'perspective',\n 'perspective-origin',\n 'pointer-events',\n 'position',\n 'quotes',\n 'resize',\n 'right',\n 'src', // @font-face\n 'tab-size',\n 'table-layout',\n 'text-align',\n 'text-align-last',\n 'text-decoration',\n 'text-decoration-color',\n 'text-decoration-line',\n 'text-decoration-style',\n 'text-indent',\n 'text-overflow',\n 'text-rendering',\n 'text-shadow',\n 'text-transform',\n 'text-underline-position',\n 'top',\n 'transform',\n 'transform-origin',\n 'transform-style',\n 'transition',\n 'transition-delay',\n 'transition-duration',\n 'transition-property',\n 'transition-timing-function',\n 'unicode-bidi',\n 'vertical-align',\n 'visibility',\n 'white-space',\n 'widows',\n 'width',\n 'word-break',\n 'word-spacing',\n 'word-wrap',\n 'z-index'\n // reverse makes sure longer attributes `font-weight` are matched fully\n // instead of getting false positives on say `font`\n].reverse();\n\n/**\n * @param {string} value\n * @returns {RegExp}\n * */\n\n/**\n * @param {RegExp | string } re\n * @returns {string}\n */\nfunction source(re) {\n if (!re) return null;\n if (typeof re === \"string\") return re;\n\n return re.source;\n}\n\n/**\n * @param {RegExp | string } re\n * @returns {string}\n */\nfunction lookahead(re) {\n return concat('(?=', re, ')');\n}\n\n/**\n * @param {...(RegExp | string) } args\n * @returns {string}\n */\nfunction concat(...args) {\n const joined = args.map((x) => source(x)).join(\"\");\n return joined;\n}\n\n/*\nLanguage: CSS\nCategory: common, css\nWebsite: https://developer.mozilla.org/en-US/docs/Web/CSS\n*/\n\n/** @type LanguageFn */\nfunction css(hljs) {\n const modes = MODES(hljs);\n const FUNCTION_DISPATCH = {\n className: \"built_in\",\n begin: /[\\w-]+(?=\\()/\n };\n const VENDOR_PREFIX = {\n begin: /-(webkit|moz|ms|o)-(?=[a-z])/\n };\n const AT_MODIFIERS = \"and or not only\";\n const AT_PROPERTY_RE = /@-?\\w[\\w]*(-\\w+)*/; // @-webkit-keyframes\n const IDENT_RE = '[a-zA-Z-][a-zA-Z0-9_-]*';\n const STRINGS = [\n hljs.APOS_STRING_MODE,\n hljs.QUOTE_STRING_MODE\n ];\n\n return {\n name: 'CSS',\n case_insensitive: true,\n illegal: /[=|'\\$]/,\n keywords: {\n keyframePosition: \"from to\"\n },\n classNameAliases: {\n // for visual continuity with `tag {}` and because we\n // don't have a great class for this?\n keyframePosition: \"selector-tag\"\n },\n contains: [\n hljs.C_BLOCK_COMMENT_MODE,\n VENDOR_PREFIX,\n // to recognize keyframe 40% etc which are outside the scope of our\n // attribute value mode\n hljs.CSS_NUMBER_MODE,\n {\n className: 'selector-id',\n begin: /#[A-Za-z0-9_-]+/,\n relevance: 0\n },\n {\n className: 'selector-class',\n begin: '\\\\.' + IDENT_RE,\n relevance: 0\n },\n modes.ATTRIBUTE_SELECTOR_MODE,\n {\n className: 'selector-pseudo',\n variants: [\n {\n begin: ':(' + PSEUDO_CLASSES.join('|') + ')'\n },\n {\n begin: '::(' + PSEUDO_ELEMENTS.join('|') + ')'\n }\n ]\n },\n // we may actually need this (12/2020)\n // { // pseudo-selector params\n // begin: /\\(/,\n // end: /\\)/,\n // contains: [ hljs.CSS_NUMBER_MODE ]\n // },\n {\n className: 'attribute',\n begin: '\\\\b(' + ATTRIBUTES.join('|') + ')\\\\b'\n },\n // attribute values\n {\n begin: ':',\n end: '[;}]',\n contains: [\n modes.HEXCOLOR,\n modes.IMPORTANT,\n hljs.CSS_NUMBER_MODE,\n ...STRINGS,\n // needed to highlight these as strings and to avoid issues with\n // illegal characters that might be inside urls that would tigger the\n // languages illegal stack\n {\n begin: /(url|data-uri)\\(/,\n end: /\\)/,\n relevance: 0, // from keywords\n keywords: {\n built_in: \"url data-uri\"\n },\n contains: [\n {\n className: \"string\",\n // any character other than `)` as in `url()` will be the start\n // of a string, which ends with `)` (from the parent mode)\n begin: /[^)]/,\n endsWithParent: true,\n excludeEnd: true\n }\n ]\n },\n FUNCTION_DISPATCH\n ]\n },\n {\n begin: lookahead(/@/),\n end: '[{;]',\n relevance: 0,\n illegal: /:/, // break on Less variables @var: ...\n contains: [\n {\n className: 'keyword',\n begin: AT_PROPERTY_RE\n },\n {\n begin: /\\s/,\n endsWithParent: true,\n excludeEnd: true,\n relevance: 0,\n keywords: {\n $pattern: /[a-z-]+/,\n keyword: AT_MODIFIERS,\n attribute: MEDIA_FEATURES.join(\" \")\n },\n contains: [\n {\n begin: /[a-z-]+(?=:)/,\n className: \"attribute\"\n },\n ...STRINGS,\n hljs.CSS_NUMBER_MODE\n ]\n }\n ]\n },\n {\n className: 'selector-tag',\n begin: '\\\\b(' + TAGS.join('|') + ')\\\\b'\n }\n ]\n };\n}\n\nmodule.exports = css;\n","/*\nLanguage: Diff\nDescription: Unified and context diff\nAuthor: Vasily Polovnyov \nWebsite: https://www.gnu.org/software/diffutils/\nCategory: common\n*/\n\n/** @type LanguageFn */\nfunction diff(hljs) {\n return {\n name: 'Diff',\n aliases: ['patch'],\n contains: [\n {\n className: 'meta',\n relevance: 10,\n variants: [\n {\n begin: /^@@ +-\\d+,\\d+ +\\+\\d+,\\d+ +@@/\n },\n {\n begin: /^\\*\\*\\* +\\d+,\\d+ +\\*\\*\\*\\*$/\n },\n {\n begin: /^--- +\\d+,\\d+ +----$/\n }\n ]\n },\n {\n className: 'comment',\n variants: [\n {\n begin: /Index: /,\n end: /$/\n },\n {\n begin: /^index/,\n end: /$/\n },\n {\n begin: /={3,}/,\n end: /$/\n },\n {\n begin: /^-{3}/,\n end: /$/\n },\n {\n begin: /^\\*{3} /,\n end: /$/\n },\n {\n begin: /^\\+{3}/,\n end: /$/\n },\n {\n begin: /^\\*{15}$/\n },\n {\n begin: /^diff --git/,\n end: /$/\n }\n ]\n },\n {\n className: 'addition',\n begin: /^\\+/,\n end: /$/\n },\n {\n className: 'deletion',\n begin: /^-/,\n end: /$/\n },\n {\n className: 'addition',\n begin: /^!/,\n end: /$/\n }\n ]\n };\n}\n\nmodule.exports = diff;\n","/*\nLanguage: Dockerfile\nRequires: bash.js\nAuthor: Alexis Hénaut \nDescription: language definition for Dockerfile files\nWebsite: https://docs.docker.com/engine/reference/builder/\nCategory: config\n*/\n\n/** @type LanguageFn */\nfunction dockerfile(hljs) {\n return {\n name: 'Dockerfile',\n aliases: ['docker'],\n case_insensitive: true,\n keywords: 'from maintainer expose env arg user onbuild stopsignal',\n contains: [\n hljs.HASH_COMMENT_MODE,\n hljs.APOS_STRING_MODE,\n hljs.QUOTE_STRING_MODE,\n hljs.NUMBER_MODE,\n {\n beginKeywords: 'run cmd entrypoint volume add copy workdir label healthcheck shell',\n starts: {\n end: /[^\\\\]$/,\n subLanguage: 'bash'\n }\n }\n ],\n illegal: '\nContributors: Anton Kochkov \nWebsite: https://en.wikipedia.org/wiki/Batch_file\n*/\n\n/** @type LanguageFn */\nfunction dos(hljs) {\n const COMMENT = hljs.COMMENT(\n /^\\s*@?rem\\b/, /$/,\n {\n relevance: 10\n }\n );\n const LABEL = {\n className: 'symbol',\n begin: '^\\\\s*[A-Za-z._?][A-Za-z0-9_$#@~.?]*(:|\\\\s+label)',\n relevance: 0\n };\n return {\n name: 'Batch file (DOS)',\n aliases: [\n 'bat',\n 'cmd'\n ],\n case_insensitive: true,\n illegal: /\\/\\*/,\n keywords: {\n keyword:\n 'if else goto for in do call exit not exist errorlevel defined ' +\n 'equ neq lss leq gtr geq',\n built_in:\n 'prn nul lpt3 lpt2 lpt1 con com4 com3 com2 com1 aux ' +\n 'shift cd dir echo setlocal endlocal set pause copy ' +\n 'append assoc at attrib break cacls cd chcp chdir chkdsk chkntfs cls cmd color ' +\n 'comp compact convert date dir diskcomp diskcopy doskey erase fs ' +\n 'find findstr format ftype graftabl help keyb label md mkdir mode more move path ' +\n 'pause print popd pushd promt rd recover rem rename replace restore rmdir shift ' +\n 'sort start subst time title tree type ver verify vol ' +\n // winutils\n 'ping net ipconfig taskkill xcopy ren del'\n },\n contains: [\n {\n className: 'variable',\n begin: /%%[^ ]|%[^ ]+?%|![^ ]+?!/\n },\n {\n className: 'function',\n begin: LABEL.begin,\n end: 'goto:eof',\n contains: [\n hljs.inherit(hljs.TITLE_MODE, {\n begin: '([_a-zA-Z]\\\\w*\\\\.)*([_a-zA-Z]\\\\w*:)?[_a-zA-Z]\\\\w*'\n }),\n COMMENT\n ]\n },\n {\n className: 'number',\n begin: '\\\\b\\\\d+',\n relevance: 0\n },\n COMMENT\n ]\n };\n}\n\nmodule.exports = dos;\n","/*\nLanguage: Gradle\nDescription: Gradle is an open-source build automation tool focused on flexibility and performance.\nWebsite: https://gradle.org\nAuthor: Damian Mee \n*/\n\nfunction gradle(hljs) {\n return {\n name: 'Gradle',\n case_insensitive: true,\n keywords: {\n keyword:\n 'task project allprojects subprojects artifacts buildscript configurations ' +\n 'dependencies repositories sourceSets description delete from into include ' +\n 'exclude source classpath destinationDir includes options sourceCompatibility ' +\n 'targetCompatibility group flatDir doLast doFirst flatten todir fromdir ant ' +\n 'def abstract break case catch continue default do else extends final finally ' +\n 'for if implements instanceof native new private protected public return static ' +\n 'switch synchronized throw throws transient try volatile while strictfp package ' +\n 'import false null super this true antlrtask checkstyle codenarc copy boolean ' +\n 'byte char class double float int interface long short void compile runTime ' +\n 'file fileTree abs any append asList asWritable call collect compareTo count ' +\n 'div dump each eachByte eachFile eachLine every find findAll flatten getAt ' +\n 'getErr getIn getOut getText grep immutable inject inspect intersect invokeMethods ' +\n 'isCase join leftShift minus multiply newInputStream newOutputStream newPrintWriter ' +\n 'newReader newWriter next plus pop power previous print println push putAt read ' +\n 'readBytes readLines reverse reverseEach round size sort splitEachLine step subMap ' +\n 'times toInteger toList tokenize upto waitForOrKill withPrintWriter withReader ' +\n 'withStream withWriter withWriterAppend write writeLine'\n },\n contains: [\n hljs.C_LINE_COMMENT_MODE,\n hljs.C_BLOCK_COMMENT_MODE,\n hljs.APOS_STRING_MODE,\n hljs.QUOTE_STRING_MODE,\n hljs.NUMBER_MODE,\n hljs.REGEXP_MODE\n\n ]\n };\n}\n\nmodule.exports = gradle;\n","/**\n * @param {string} value\n * @returns {RegExp}\n * */\n\n/**\n * @param {RegExp | string } re\n * @returns {string}\n */\nfunction source(re) {\n if (!re) return null;\n if (typeof re === \"string\") return re;\n\n return re.source;\n}\n\n/**\n * @param {RegExp | string } re\n * @returns {string}\n */\nfunction lookahead(re) {\n return concat('(?=', re, ')');\n}\n\n/**\n * @param {...(RegExp | string) } args\n * @returns {string}\n */\nfunction concat(...args) {\n const joined = args.map((x) => source(x)).join(\"\");\n return joined;\n}\n\n/*\n Language: Groovy\n Author: Guillaume Laforge \n Description: Groovy programming language implementation inspired from Vsevolod's Java mode\n Website: https://groovy-lang.org\n */\n\nfunction variants(variants, obj = {}) {\n obj.variants = variants;\n return obj;\n}\n\nfunction groovy(hljs) {\n const IDENT_RE = '[A-Za-z0-9_$]+';\n const COMMENT = variants([\n hljs.C_LINE_COMMENT_MODE,\n hljs.C_BLOCK_COMMENT_MODE,\n hljs.COMMENT(\n '/\\\\*\\\\*',\n '\\\\*/',\n {\n relevance: 0,\n contains: [\n {\n // eat up @'s in emails to prevent them to be recognized as doctags\n begin: /\\w+@/,\n relevance: 0\n },\n {\n className: 'doctag',\n begin: '@[A-Za-z]+'\n }\n ]\n }\n )\n ]);\n const REGEXP = {\n className: 'regexp',\n begin: /~?\\/[^\\/\\n]+\\//,\n contains: [ hljs.BACKSLASH_ESCAPE ]\n };\n const NUMBER = variants([\n hljs.BINARY_NUMBER_MODE,\n hljs.C_NUMBER_MODE\n ]);\n const STRING = variants([\n {\n begin: /\"\"\"/,\n end: /\"\"\"/\n },\n {\n begin: /'''/,\n end: /'''/\n },\n {\n begin: \"\\\\$/\",\n end: \"/\\\\$\",\n relevance: 10\n },\n hljs.APOS_STRING_MODE,\n hljs.QUOTE_STRING_MODE\n ],\n {\n className: \"string\"\n }\n );\n\n return {\n name: 'Groovy',\n keywords: {\n built_in: 'this super',\n literal: 'true false null',\n keyword:\n 'byte short char int long boolean float double void ' +\n // groovy specific keywords\n 'def as in assert trait ' +\n // common keywords with Java\n 'abstract static volatile transient public private protected synchronized final ' +\n 'class interface enum if else for while switch case break default continue ' +\n 'throw throws try catch finally implements extends new import package return instanceof'\n },\n contains: [\n hljs.SHEBANG({\n binary: \"groovy\",\n relevance: 10\n }),\n COMMENT,\n STRING,\n REGEXP,\n NUMBER,\n {\n className: 'class',\n beginKeywords: 'class interface trait enum',\n end: /\\{/,\n illegal: ':',\n contains: [\n {\n beginKeywords: 'extends implements'\n },\n hljs.UNDERSCORE_TITLE_MODE\n ]\n },\n {\n className: 'meta',\n begin: '@[A-Za-z]+',\n relevance: 0\n },\n {\n // highlight map keys and named parameters as attrs\n className: 'attr',\n begin: IDENT_RE + '[ \\t]*:',\n relevance: 0\n },\n {\n // catch middle element of the ternary operator\n // to avoid highlight it as a label, named parameter, or map key\n begin: /\\?/,\n end: /:/,\n relevance: 0,\n contains: [\n COMMENT,\n STRING,\n REGEXP,\n NUMBER,\n 'self'\n ]\n },\n {\n // highlight labeled statements\n className: 'symbol',\n begin: '^[ \\t]*' + lookahead(IDENT_RE + ':'),\n excludeBegin: true,\n end: IDENT_RE + ':',\n relevance: 0\n }\n ],\n illegal: /#|<\\//\n };\n}\n\nmodule.exports = groovy;\n","/**\n * @param {string} value\n * @returns {RegExp}\n * */\n\n/**\n * @param {RegExp | string } re\n * @returns {string}\n */\nfunction source(re) {\n if (!re) return null;\n if (typeof re === \"string\") return re;\n\n return re.source;\n}\n\n/**\n * @param {...(RegExp | string) } args\n * @returns {string}\n */\nfunction concat(...args) {\n const joined = args.map((x) => source(x)).join(\"\");\n return joined;\n}\n\n/*\nLanguage: HTTP\nDescription: HTTP request and response headers with automatic body highlighting\nAuthor: Ivan Sagalaev \nCategory: common, protocols\nWebsite: https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview\n*/\n\nfunction http(hljs) {\n const VERSION = 'HTTP/(2|1\\\\.[01])';\n const HEADER_NAME = /[A-Za-z][A-Za-z0-9-]*/;\n const HEADER = {\n className: 'attribute',\n begin: concat('^', HEADER_NAME, '(?=\\\\:\\\\s)'),\n starts: {\n contains: [\n {\n className: \"punctuation\",\n begin: /: /,\n relevance: 0,\n starts: {\n end: '$',\n relevance: 0\n }\n }\n ]\n }\n };\n const HEADERS_AND_BODY = [\n HEADER,\n {\n begin: '\\\\n\\\\n',\n starts: { subLanguage: [], endsWithParent: true }\n }\n ];\n\n return {\n name: 'HTTP',\n aliases: ['https'],\n illegal: /\\S/,\n contains: [\n // response\n {\n begin: '^(?=' + VERSION + \" \\\\d{3})\",\n end: /$/,\n contains: [\n {\n className: \"meta\",\n begin: VERSION\n },\n {\n className: 'number', begin: '\\\\b\\\\d{3}\\\\b'\n }\n ],\n starts: {\n end: /\\b\\B/,\n illegal: /\\S/,\n contains: HEADERS_AND_BODY\n }\n },\n // request\n {\n begin: '(?=^[A-Z]+ (.*?) ' + VERSION + '$)',\n end: /$/,\n contains: [\n {\n className: 'string',\n begin: ' ',\n end: ' ',\n excludeBegin: true,\n excludeEnd: true\n },\n {\n className: \"meta\",\n begin: VERSION\n },\n {\n className: 'keyword',\n begin: '[A-Z]+'\n }\n ],\n starts: {\n end: /\\b\\B/,\n illegal: /\\S/,\n contains: HEADERS_AND_BODY\n }\n },\n // to allow headers to work even without a preamble\n hljs.inherit(HEADER, {\n relevance: 0\n })\n ]\n };\n}\n\nmodule.exports = http;\n","// https://docs.oracle.com/javase/specs/jls/se15/html/jls-3.html#jls-3.10\nvar decimalDigits = '[0-9](_*[0-9])*';\nvar frac = `\\\\.(${decimalDigits})`;\nvar hexDigits = '[0-9a-fA-F](_*[0-9a-fA-F])*';\nvar NUMERIC = {\n className: 'number',\n variants: [\n // DecimalFloatingPointLiteral\n // including ExponentPart\n { begin: `(\\\\b(${decimalDigits})((${frac})|\\\\.)?|(${frac}))` +\n `[eE][+-]?(${decimalDigits})[fFdD]?\\\\b` },\n // excluding ExponentPart\n { begin: `\\\\b(${decimalDigits})((${frac})[fFdD]?\\\\b|\\\\.([fFdD]\\\\b)?)` },\n { begin: `(${frac})[fFdD]?\\\\b` },\n { begin: `\\\\b(${decimalDigits})[fFdD]\\\\b` },\n\n // HexadecimalFloatingPointLiteral\n { begin: `\\\\b0[xX]((${hexDigits})\\\\.?|(${hexDigits})?\\\\.(${hexDigits}))` +\n `[pP][+-]?(${decimalDigits})[fFdD]?\\\\b` },\n\n // DecimalIntegerLiteral\n { begin: '\\\\b(0|[1-9](_*[0-9])*)[lL]?\\\\b' },\n\n // HexIntegerLiteral\n { begin: `\\\\b0[xX](${hexDigits})[lL]?\\\\b` },\n\n // OctalIntegerLiteral\n { begin: '\\\\b0(_*[0-7])*[lL]?\\\\b' },\n\n // BinaryIntegerLiteral\n { begin: '\\\\b0[bB][01](_*[01])*[lL]?\\\\b' },\n ],\n relevance: 0\n};\n\n/*\nLanguage: Java\nAuthor: Vsevolod Solovyov \nCategory: common, enterprise\nWebsite: https://www.java.com/\n*/\n\nfunction java(hljs) {\n var JAVA_IDENT_RE = '[\\u00C0-\\u02B8a-zA-Z_$][\\u00C0-\\u02B8a-zA-Z_$0-9]*';\n var GENERIC_IDENT_RE = JAVA_IDENT_RE + '(<' + JAVA_IDENT_RE + '(\\\\s*,\\\\s*' + JAVA_IDENT_RE + ')*>)?';\n var KEYWORDS = 'false synchronized int abstract float private char boolean var static null if const ' +\n 'for true while long strictfp finally protected import native final void ' +\n 'enum else break transient catch instanceof byte super volatile case assert short ' +\n 'package default double public try this switch continue throws protected public private ' +\n 'module requires exports do';\n\n var ANNOTATION = {\n className: 'meta',\n begin: '@' + JAVA_IDENT_RE,\n contains: [\n {\n begin: /\\(/,\n end: /\\)/,\n contains: [\"self\"] // allow nested () inside our annotation\n },\n ]\n };\n const NUMBER = NUMERIC;\n\n return {\n name: 'Java',\n aliases: ['jsp'],\n keywords: KEYWORDS,\n illegal: /<\\/|#/,\n contains: [\n hljs.COMMENT(\n '/\\\\*\\\\*',\n '\\\\*/',\n {\n relevance: 0,\n contains: [\n {\n // eat up @'s in emails to prevent them to be recognized as doctags\n begin: /\\w+@/, relevance: 0\n },\n {\n className: 'doctag',\n begin: '@[A-Za-z]+'\n }\n ]\n }\n ),\n // relevance boost\n {\n begin: /import java\\.[a-z]+\\./,\n keywords: \"import\",\n relevance: 2\n },\n hljs.C_LINE_COMMENT_MODE,\n hljs.C_BLOCK_COMMENT_MODE,\n hljs.APOS_STRING_MODE,\n hljs.QUOTE_STRING_MODE,\n {\n className: 'class',\n beginKeywords: 'class interface enum', end: /[{;=]/, excludeEnd: true,\n // TODO: can this be removed somehow?\n // an extra boost because Java is more popular than other languages with\n // this same syntax feature (this is just to preserve our tests passing\n // for now)\n relevance: 1,\n keywords: 'class interface enum',\n illegal: /[:\"\\[\\]]/,\n contains: [\n { beginKeywords: 'extends implements' },\n hljs.UNDERSCORE_TITLE_MODE\n ]\n },\n {\n // Expression keywords prevent 'keyword Name(...)' from being\n // recognized as a function definition\n beginKeywords: 'new throw return else',\n relevance: 0\n },\n {\n className: 'class',\n begin: 'record\\\\s+' + hljs.UNDERSCORE_IDENT_RE + '\\\\s*\\\\(',\n returnBegin: true,\n excludeEnd: true,\n end: /[{;=]/,\n keywords: KEYWORDS,\n contains: [\n { beginKeywords: \"record\" },\n {\n begin: hljs.UNDERSCORE_IDENT_RE + '\\\\s*\\\\(',\n returnBegin: true,\n relevance: 0,\n contains: [hljs.UNDERSCORE_TITLE_MODE]\n },\n {\n className: 'params',\n begin: /\\(/, end: /\\)/,\n keywords: KEYWORDS,\n relevance: 0,\n contains: [\n hljs.C_BLOCK_COMMENT_MODE\n ]\n },\n hljs.C_LINE_COMMENT_MODE,\n hljs.C_BLOCK_COMMENT_MODE\n ]\n },\n {\n className: 'function',\n begin: '(' + GENERIC_IDENT_RE + '\\\\s+)+' + hljs.UNDERSCORE_IDENT_RE + '\\\\s*\\\\(', returnBegin: true, end: /[{;=]/,\n excludeEnd: true,\n keywords: KEYWORDS,\n contains: [\n {\n begin: hljs.UNDERSCORE_IDENT_RE + '\\\\s*\\\\(', returnBegin: true,\n relevance: 0,\n contains: [hljs.UNDERSCORE_TITLE_MODE]\n },\n {\n className: 'params',\n begin: /\\(/, end: /\\)/,\n keywords: KEYWORDS,\n relevance: 0,\n contains: [\n ANNOTATION,\n hljs.APOS_STRING_MODE,\n hljs.QUOTE_STRING_MODE,\n NUMBER,\n hljs.C_BLOCK_COMMENT_MODE\n ]\n },\n hljs.C_LINE_COMMENT_MODE,\n hljs.C_BLOCK_COMMENT_MODE\n ]\n },\n NUMBER,\n ANNOTATION\n ]\n };\n}\n\nmodule.exports = java;\n","const IDENT_RE = '[A-Za-z$_][0-9A-Za-z$_]*';\nconst KEYWORDS = [\n \"as\", // for exports\n \"in\",\n \"of\",\n \"if\",\n \"for\",\n \"while\",\n \"finally\",\n \"var\",\n \"new\",\n \"function\",\n \"do\",\n \"return\",\n \"void\",\n \"else\",\n \"break\",\n \"catch\",\n \"instanceof\",\n \"with\",\n \"throw\",\n \"case\",\n \"default\",\n \"try\",\n \"switch\",\n \"continue\",\n \"typeof\",\n \"delete\",\n \"let\",\n \"yield\",\n \"const\",\n \"class\",\n // JS handles these with a special rule\n // \"get\",\n // \"set\",\n \"debugger\",\n \"async\",\n \"await\",\n \"static\",\n \"import\",\n \"from\",\n \"export\",\n \"extends\"\n];\nconst LITERALS = [\n \"true\",\n \"false\",\n \"null\",\n \"undefined\",\n \"NaN\",\n \"Infinity\"\n];\n\nconst TYPES = [\n \"Intl\",\n \"DataView\",\n \"Number\",\n \"Math\",\n \"Date\",\n \"String\",\n \"RegExp\",\n \"Object\",\n \"Function\",\n \"Boolean\",\n \"Error\",\n \"Symbol\",\n \"Set\",\n \"Map\",\n \"WeakSet\",\n \"WeakMap\",\n \"Proxy\",\n \"Reflect\",\n \"JSON\",\n \"Promise\",\n \"Float64Array\",\n \"Int16Array\",\n \"Int32Array\",\n \"Int8Array\",\n \"Uint16Array\",\n \"Uint32Array\",\n \"Float32Array\",\n \"Array\",\n \"Uint8Array\",\n \"Uint8ClampedArray\",\n \"ArrayBuffer\",\n \"BigInt64Array\",\n \"BigUint64Array\",\n \"BigInt\"\n];\n\nconst ERROR_TYPES = [\n \"EvalError\",\n \"InternalError\",\n \"RangeError\",\n \"ReferenceError\",\n \"SyntaxError\",\n \"TypeError\",\n \"URIError\"\n];\n\nconst BUILT_IN_GLOBALS = [\n \"setInterval\",\n \"setTimeout\",\n \"clearInterval\",\n \"clearTimeout\",\n\n \"require\",\n \"exports\",\n\n \"eval\",\n \"isFinite\",\n \"isNaN\",\n \"parseFloat\",\n \"parseInt\",\n \"decodeURI\",\n \"decodeURIComponent\",\n \"encodeURI\",\n \"encodeURIComponent\",\n \"escape\",\n \"unescape\"\n];\n\nconst BUILT_IN_VARIABLES = [\n \"arguments\",\n \"this\",\n \"super\",\n \"console\",\n \"window\",\n \"document\",\n \"localStorage\",\n \"module\",\n \"global\" // Node.js\n];\n\nconst BUILT_INS = [].concat(\n BUILT_IN_GLOBALS,\n BUILT_IN_VARIABLES,\n TYPES,\n ERROR_TYPES\n);\n\n/**\n * @param {string} value\n * @returns {RegExp}\n * */\n\n/**\n * @param {RegExp | string } re\n * @returns {string}\n */\nfunction source(re) {\n if (!re) return null;\n if (typeof re === \"string\") return re;\n\n return re.source;\n}\n\n/**\n * @param {RegExp | string } re\n * @returns {string}\n */\nfunction lookahead(re) {\n return concat('(?=', re, ')');\n}\n\n/**\n * @param {...(RegExp | string) } args\n * @returns {string}\n */\nfunction concat(...args) {\n const joined = args.map((x) => source(x)).join(\"\");\n return joined;\n}\n\n/*\nLanguage: JavaScript\nDescription: JavaScript (JS) is a lightweight, interpreted, or just-in-time compiled programming language with first-class functions.\nCategory: common, scripting\nWebsite: https://developer.mozilla.org/en-US/docs/Web/JavaScript\n*/\n\n/** @type LanguageFn */\nfunction javascript(hljs) {\n /**\n * Takes a string like \" {\n const tag = \"',\n end: ''\n };\n const XML_TAG = {\n begin: /<[A-Za-z0-9\\\\._:-]+/,\n end: /\\/[A-Za-z0-9\\\\._:-]+>|\\/>/,\n /**\n * @param {RegExpMatchArray} match\n * @param {CallbackResponse} response\n */\n isTrulyOpeningTag: (match, response) => {\n const afterMatchIndex = match[0].length + match.index;\n const nextChar = match.input[afterMatchIndex];\n // nested type?\n // HTML should not include another raw `<` inside a tag\n // But a type might: `>`, etc.\n if (nextChar === \"<\") {\n response.ignoreMatch();\n return;\n }\n // \n // This is now either a tag or a type.\n if (nextChar === \">\") {\n // if we cannot find a matching closing tag, then we\n // will ignore it\n if (!hasClosingTag(match, { after: afterMatchIndex })) {\n response.ignoreMatch();\n }\n }\n }\n };\n const KEYWORDS$1 = {\n $pattern: IDENT_RE,\n keyword: KEYWORDS,\n literal: LITERALS,\n built_in: BUILT_INS\n };\n\n // https://tc39.es/ecma262/#sec-literals-numeric-literals\n const decimalDigits = '[0-9](_?[0-9])*';\n const frac = `\\\\.(${decimalDigits})`;\n // DecimalIntegerLiteral, including Annex B NonOctalDecimalIntegerLiteral\n // https://tc39.es/ecma262/#sec-additional-syntax-numeric-literals\n const decimalInteger = `0|[1-9](_?[0-9])*|0[0-7]*[89][0-9]*`;\n const NUMBER = {\n className: 'number',\n variants: [\n // DecimalLiteral\n { begin: `(\\\\b(${decimalInteger})((${frac})|\\\\.)?|(${frac}))` +\n `[eE][+-]?(${decimalDigits})\\\\b` },\n { begin: `\\\\b(${decimalInteger})\\\\b((${frac})\\\\b|\\\\.)?|(${frac})\\\\b` },\n\n // DecimalBigIntegerLiteral\n { begin: `\\\\b(0|[1-9](_?[0-9])*)n\\\\b` },\n\n // NonDecimalIntegerLiteral\n { begin: \"\\\\b0[xX][0-9a-fA-F](_?[0-9a-fA-F])*n?\\\\b\" },\n { begin: \"\\\\b0[bB][0-1](_?[0-1])*n?\\\\b\" },\n { begin: \"\\\\b0[oO][0-7](_?[0-7])*n?\\\\b\" },\n\n // LegacyOctalIntegerLiteral (does not include underscore separators)\n // https://tc39.es/ecma262/#sec-additional-syntax-numeric-literals\n { begin: \"\\\\b0[0-7]+n?\\\\b\" },\n ],\n relevance: 0\n };\n\n const SUBST = {\n className: 'subst',\n begin: '\\\\$\\\\{',\n end: '\\\\}',\n keywords: KEYWORDS$1,\n contains: [] // defined later\n };\n const HTML_TEMPLATE = {\n begin: 'html`',\n end: '',\n starts: {\n end: '`',\n returnEnd: false,\n contains: [\n hljs.BACKSLASH_ESCAPE,\n SUBST\n ],\n subLanguage: 'xml'\n }\n };\n const CSS_TEMPLATE = {\n begin: 'css`',\n end: '',\n starts: {\n end: '`',\n returnEnd: false,\n contains: [\n hljs.BACKSLASH_ESCAPE,\n SUBST\n ],\n subLanguage: 'css'\n }\n };\n const TEMPLATE_STRING = {\n className: 'string',\n begin: '`',\n end: '`',\n contains: [\n hljs.BACKSLASH_ESCAPE,\n SUBST\n ]\n };\n const JSDOC_COMMENT = hljs.COMMENT(\n /\\/\\*\\*(?!\\/)/,\n '\\\\*/',\n {\n relevance: 0,\n contains: [\n {\n className: 'doctag',\n begin: '@[A-Za-z]+',\n contains: [\n {\n className: 'type',\n begin: '\\\\{',\n end: '\\\\}',\n relevance: 0\n },\n {\n className: 'variable',\n begin: IDENT_RE$1 + '(?=\\\\s*(-)|$)',\n endsParent: true,\n relevance: 0\n },\n // eat spaces (not newlines) so we can find\n // types or variables\n {\n begin: /(?=[^\\n])\\s/,\n relevance: 0\n }\n ]\n }\n ]\n }\n );\n const COMMENT = {\n className: \"comment\",\n variants: [\n JSDOC_COMMENT,\n hljs.C_BLOCK_COMMENT_MODE,\n hljs.C_LINE_COMMENT_MODE\n ]\n };\n const SUBST_INTERNALS = [\n hljs.APOS_STRING_MODE,\n hljs.QUOTE_STRING_MODE,\n HTML_TEMPLATE,\n CSS_TEMPLATE,\n TEMPLATE_STRING,\n NUMBER,\n hljs.REGEXP_MODE\n ];\n SUBST.contains = SUBST_INTERNALS\n .concat({\n // we need to pair up {} inside our subst to prevent\n // it from ending too early by matching another }\n begin: /\\{/,\n end: /\\}/,\n keywords: KEYWORDS$1,\n contains: [\n \"self\"\n ].concat(SUBST_INTERNALS)\n });\n const SUBST_AND_COMMENTS = [].concat(COMMENT, SUBST.contains);\n const PARAMS_CONTAINS = SUBST_AND_COMMENTS.concat([\n // eat recursive parens in sub expressions\n {\n begin: /\\(/,\n end: /\\)/,\n keywords: KEYWORDS$1,\n contains: [\"self\"].concat(SUBST_AND_COMMENTS)\n }\n ]);\n const PARAMS = {\n className: 'params',\n begin: /\\(/,\n end: /\\)/,\n excludeBegin: true,\n excludeEnd: true,\n keywords: KEYWORDS$1,\n contains: PARAMS_CONTAINS\n };\n\n return {\n name: 'Javascript',\n aliases: ['js', 'jsx', 'mjs', 'cjs'],\n keywords: KEYWORDS$1,\n // this will be extended by TypeScript\n exports: { PARAMS_CONTAINS },\n illegal: /#(?![$_A-z])/,\n contains: [\n hljs.SHEBANG({\n label: \"shebang\",\n binary: \"node\",\n relevance: 5\n }),\n {\n label: \"use_strict\",\n className: 'meta',\n relevance: 10,\n begin: /^\\s*['\"]use (strict|asm)['\"]/\n },\n hljs.APOS_STRING_MODE,\n hljs.QUOTE_STRING_MODE,\n HTML_TEMPLATE,\n CSS_TEMPLATE,\n TEMPLATE_STRING,\n COMMENT,\n NUMBER,\n { // object attr container\n begin: concat(/[{,\\n]\\s*/,\n // we need to look ahead to make sure that we actually have an\n // attribute coming up so we don't steal a comma from a potential\n // \"value\" container\n //\n // NOTE: this might not work how you think. We don't actually always\n // enter this mode and stay. Instead it might merely match `,\n // ` and then immediately end after the , because it\n // fails to find any actual attrs. But this still does the job because\n // it prevents the value contain rule from grabbing this instead and\n // prevening this rule from firing when we actually DO have keys.\n lookahead(concat(\n // we also need to allow for multiple possible comments inbetween\n // the first key:value pairing\n /(((\\/\\/.*$)|(\\/\\*(\\*[^/]|[^*])*\\*\\/))\\s*)*/,\n IDENT_RE$1 + '\\\\s*:'))),\n relevance: 0,\n contains: [\n {\n className: 'attr',\n begin: IDENT_RE$1 + lookahead('\\\\s*:'),\n relevance: 0\n }\n ]\n },\n { // \"value\" container\n begin: '(' + hljs.RE_STARTERS_RE + '|\\\\b(case|return|throw)\\\\b)\\\\s*',\n keywords: 'return throw case',\n contains: [\n COMMENT,\n hljs.REGEXP_MODE,\n {\n className: 'function',\n // we have to count the parens to make sure we actually have the\n // correct bounding ( ) before the =>. There could be any number of\n // sub-expressions inside also surrounded by parens.\n begin: '(\\\\(' +\n '[^()]*(\\\\(' +\n '[^()]*(\\\\(' +\n '[^()]*' +\n '\\\\)[^()]*)*' +\n '\\\\)[^()]*)*' +\n '\\\\)|' + hljs.UNDERSCORE_IDENT_RE + ')\\\\s*=>',\n returnBegin: true,\n end: '\\\\s*=>',\n contains: [\n {\n className: 'params',\n variants: [\n {\n begin: hljs.UNDERSCORE_IDENT_RE,\n relevance: 0\n },\n {\n className: null,\n begin: /\\(\\s*\\)/,\n skip: true\n },\n {\n begin: /\\(/,\n end: /\\)/,\n excludeBegin: true,\n excludeEnd: true,\n keywords: KEYWORDS$1,\n contains: PARAMS_CONTAINS\n }\n ]\n }\n ]\n },\n { // could be a comma delimited list of params to a function call\n begin: /,/, relevance: 0\n },\n {\n className: '',\n begin: /\\s/,\n end: /\\s*/,\n skip: true\n },\n { // JSX\n variants: [\n { begin: FRAGMENT.begin, end: FRAGMENT.end },\n {\n begin: XML_TAG.begin,\n // we carefully check the opening tag to see if it truly\n // is a tag and not a false positive\n 'on:begin': XML_TAG.isTrulyOpeningTag,\n end: XML_TAG.end\n }\n ],\n subLanguage: 'xml',\n contains: [\n {\n begin: XML_TAG.begin,\n end: XML_TAG.end,\n skip: true,\n contains: ['self']\n }\n ]\n }\n ],\n relevance: 0\n },\n {\n className: 'function',\n beginKeywords: 'function',\n end: /[{;]/,\n excludeEnd: true,\n keywords: KEYWORDS$1,\n contains: [\n 'self',\n hljs.inherit(hljs.TITLE_MODE, { begin: IDENT_RE$1 }),\n PARAMS\n ],\n illegal: /%/\n },\n {\n // prevent this from getting swallowed up by function\n // since they appear \"function like\"\n beginKeywords: \"while if switch catch for\"\n },\n {\n className: 'function',\n // we have to count the parens to make sure we actually have the correct\n // bounding ( ). There could be any number of sub-expressions inside\n // also surrounded by parens.\n begin: hljs.UNDERSCORE_IDENT_RE +\n '\\\\(' + // first parens\n '[^()]*(\\\\(' +\n '[^()]*(\\\\(' +\n '[^()]*' +\n '\\\\)[^()]*)*' +\n '\\\\)[^()]*)*' +\n '\\\\)\\\\s*\\\\{', // end parens\n returnBegin:true,\n contains: [\n PARAMS,\n hljs.inherit(hljs.TITLE_MODE, { begin: IDENT_RE$1 }),\n ]\n },\n // hack: prevents detection of keywords in some circumstances\n // .keyword()\n // $keyword = x\n {\n variants: [\n { begin: '\\\\.' + IDENT_RE$1 },\n { begin: '\\\\$' + IDENT_RE$1 }\n ],\n relevance: 0\n },\n { // ES6 class\n className: 'class',\n beginKeywords: 'class',\n end: /[{;=]/,\n excludeEnd: true,\n illegal: /[:\"[\\]]/,\n contains: [\n { beginKeywords: 'extends' },\n hljs.UNDERSCORE_TITLE_MODE\n ]\n },\n {\n begin: /\\b(?=constructor)/,\n end: /[{;]/,\n excludeEnd: true,\n contains: [\n hljs.inherit(hljs.TITLE_MODE, { begin: IDENT_RE$1 }),\n 'self',\n PARAMS\n ]\n },\n {\n begin: '(get|set)\\\\s+(?=' + IDENT_RE$1 + '\\\\()',\n end: /\\{/,\n keywords: \"get set\",\n contains: [\n hljs.inherit(hljs.TITLE_MODE, { begin: IDENT_RE$1 }),\n { begin: /\\(\\)/ }, // eat to avoid empty params\n PARAMS\n ]\n },\n {\n begin: /\\$[(.]/ // relevance booster for a pattern common to JS libs: `$(something)` and `$.something`\n }\n ]\n };\n}\n\nmodule.exports = javascript;\n","/*\nLanguage: JSON\nDescription: JSON (JavaScript Object Notation) is a lightweight data-interchange format.\nAuthor: Ivan Sagalaev \nWebsite: http://www.json.org\nCategory: common, protocols\n*/\n\nfunction json(hljs) {\n const LITERALS = {\n literal: 'true false null'\n };\n const ALLOWED_COMMENTS = [\n hljs.C_LINE_COMMENT_MODE,\n hljs.C_BLOCK_COMMENT_MODE\n ];\n const TYPES = [\n hljs.QUOTE_STRING_MODE,\n hljs.C_NUMBER_MODE\n ];\n const VALUE_CONTAINER = {\n end: ',',\n endsWithParent: true,\n excludeEnd: true,\n contains: TYPES,\n keywords: LITERALS\n };\n const OBJECT = {\n begin: /\\{/,\n end: /\\}/,\n contains: [\n {\n className: 'attr',\n begin: /\"/,\n end: /\"/,\n contains: [hljs.BACKSLASH_ESCAPE],\n illegal: '\\\\n'\n },\n hljs.inherit(VALUE_CONTAINER, {\n begin: /:/\n })\n ].concat(ALLOWED_COMMENTS),\n illegal: '\\\\S'\n };\n const ARRAY = {\n begin: '\\\\[',\n end: '\\\\]',\n contains: [hljs.inherit(VALUE_CONTAINER)], // inherit is a workaround for a bug that makes shared modes with endsWithParent compile only the ending of one of the parents\n illegal: '\\\\S'\n };\n TYPES.push(OBJECT, ARRAY);\n ALLOWED_COMMENTS.forEach(function(rule) {\n TYPES.push(rule);\n });\n return {\n name: 'JSON',\n contains: TYPES,\n keywords: LITERALS,\n illegal: '\\\\S'\n };\n}\n\nmodule.exports = json;\n","// https://docs.oracle.com/javase/specs/jls/se15/html/jls-3.html#jls-3.10\nvar decimalDigits = '[0-9](_*[0-9])*';\nvar frac = `\\\\.(${decimalDigits})`;\nvar hexDigits = '[0-9a-fA-F](_*[0-9a-fA-F])*';\nvar NUMERIC = {\n className: 'number',\n variants: [\n // DecimalFloatingPointLiteral\n // including ExponentPart\n { begin: `(\\\\b(${decimalDigits})((${frac})|\\\\.)?|(${frac}))` +\n `[eE][+-]?(${decimalDigits})[fFdD]?\\\\b` },\n // excluding ExponentPart\n { begin: `\\\\b(${decimalDigits})((${frac})[fFdD]?\\\\b|\\\\.([fFdD]\\\\b)?)` },\n { begin: `(${frac})[fFdD]?\\\\b` },\n { begin: `\\\\b(${decimalDigits})[fFdD]\\\\b` },\n\n // HexadecimalFloatingPointLiteral\n { begin: `\\\\b0[xX]((${hexDigits})\\\\.?|(${hexDigits})?\\\\.(${hexDigits}))` +\n `[pP][+-]?(${decimalDigits})[fFdD]?\\\\b` },\n\n // DecimalIntegerLiteral\n { begin: '\\\\b(0|[1-9](_*[0-9])*)[lL]?\\\\b' },\n\n // HexIntegerLiteral\n { begin: `\\\\b0[xX](${hexDigits})[lL]?\\\\b` },\n\n // OctalIntegerLiteral\n { begin: '\\\\b0(_*[0-7])*[lL]?\\\\b' },\n\n // BinaryIntegerLiteral\n { begin: '\\\\b0[bB][01](_*[01])*[lL]?\\\\b' },\n ],\n relevance: 0\n};\n\n/*\n Language: Kotlin\n Description: Kotlin is an OSS statically typed programming language that targets the JVM, Android, JavaScript and Native.\n Author: Sergey Mashkov \n Website: https://kotlinlang.org\n Category: common\n */\n\nfunction kotlin(hljs) {\n const KEYWORDS = {\n keyword:\n 'abstract as val var vararg get set class object open private protected public noinline ' +\n 'crossinline dynamic final enum if else do while for when throw try catch finally ' +\n 'import package is in fun override companion reified inline lateinit init ' +\n 'interface annotation data sealed internal infix operator out by constructor super ' +\n 'tailrec where const inner suspend typealias external expect actual',\n built_in:\n 'Byte Short Char Int Long Boolean Float Double Void Unit Nothing',\n literal:\n 'true false null'\n };\n const KEYWORDS_WITH_LABEL = {\n className: 'keyword',\n begin: /\\b(break|continue|return|this)\\b/,\n starts: {\n contains: [\n {\n className: 'symbol',\n begin: /@\\w+/\n }\n ]\n }\n };\n const LABEL = {\n className: 'symbol',\n begin: hljs.UNDERSCORE_IDENT_RE + '@'\n };\n\n // for string templates\n const SUBST = {\n className: 'subst',\n begin: /\\$\\{/,\n end: /\\}/,\n contains: [ hljs.C_NUMBER_MODE ]\n };\n const VARIABLE = {\n className: 'variable',\n begin: '\\\\$' + hljs.UNDERSCORE_IDENT_RE\n };\n const STRING = {\n className: 'string',\n variants: [\n {\n begin: '\"\"\"',\n end: '\"\"\"(?=[^\"])',\n contains: [\n VARIABLE,\n SUBST\n ]\n },\n // Can't use built-in modes easily, as we want to use STRING in the meta\n // context as 'meta-string' and there's no syntax to remove explicitly set\n // classNames in built-in modes.\n {\n begin: '\\'',\n end: '\\'',\n illegal: /\\n/,\n contains: [ hljs.BACKSLASH_ESCAPE ]\n },\n {\n begin: '\"',\n end: '\"',\n illegal: /\\n/,\n contains: [\n hljs.BACKSLASH_ESCAPE,\n VARIABLE,\n SUBST\n ]\n }\n ]\n };\n SUBST.contains.push(STRING);\n\n const ANNOTATION_USE_SITE = {\n className: 'meta',\n begin: '@(?:file|property|field|get|set|receiver|param|setparam|delegate)\\\\s*:(?:\\\\s*' + hljs.UNDERSCORE_IDENT_RE + ')?'\n };\n const ANNOTATION = {\n className: 'meta',\n begin: '@' + hljs.UNDERSCORE_IDENT_RE,\n contains: [\n {\n begin: /\\(/,\n end: /\\)/,\n contains: [\n hljs.inherit(STRING, {\n className: 'meta-string'\n })\n ]\n }\n ]\n };\n\n // https://kotlinlang.org/docs/reference/whatsnew11.html#underscores-in-numeric-literals\n // According to the doc above, the number mode of kotlin is the same as java 8,\n // so the code below is copied from java.js\n const KOTLIN_NUMBER_MODE = NUMERIC;\n const KOTLIN_NESTED_COMMENT = hljs.COMMENT(\n '/\\\\*', '\\\\*/',\n {\n contains: [ hljs.C_BLOCK_COMMENT_MODE ]\n }\n );\n const KOTLIN_PAREN_TYPE = {\n variants: [\n {\n className: 'type',\n begin: hljs.UNDERSCORE_IDENT_RE\n },\n {\n begin: /\\(/,\n end: /\\)/,\n contains: [] // defined later\n }\n ]\n };\n const KOTLIN_PAREN_TYPE2 = KOTLIN_PAREN_TYPE;\n KOTLIN_PAREN_TYPE2.variants[1].contains = [ KOTLIN_PAREN_TYPE ];\n KOTLIN_PAREN_TYPE.variants[1].contains = [ KOTLIN_PAREN_TYPE2 ];\n\n return {\n name: 'Kotlin',\n aliases: [ 'kt', 'kts' ],\n keywords: KEYWORDS,\n contains: [\n hljs.COMMENT(\n '/\\\\*\\\\*',\n '\\\\*/',\n {\n relevance: 0,\n contains: [\n {\n className: 'doctag',\n begin: '@[A-Za-z]+'\n }\n ]\n }\n ),\n hljs.C_LINE_COMMENT_MODE,\n KOTLIN_NESTED_COMMENT,\n KEYWORDS_WITH_LABEL,\n LABEL,\n ANNOTATION_USE_SITE,\n ANNOTATION,\n {\n className: 'function',\n beginKeywords: 'fun',\n end: '[(]|$',\n returnBegin: true,\n excludeEnd: true,\n keywords: KEYWORDS,\n relevance: 5,\n contains: [\n {\n begin: hljs.UNDERSCORE_IDENT_RE + '\\\\s*\\\\(',\n returnBegin: true,\n relevance: 0,\n contains: [ hljs.UNDERSCORE_TITLE_MODE ]\n },\n {\n className: 'type',\n begin: //,\n keywords: 'reified',\n relevance: 0\n },\n {\n className: 'params',\n begin: /\\(/,\n end: /\\)/,\n endsParent: true,\n keywords: KEYWORDS,\n relevance: 0,\n contains: [\n {\n begin: /:/,\n end: /[=,\\/]/,\n endsWithParent: true,\n contains: [\n KOTLIN_PAREN_TYPE,\n hljs.C_LINE_COMMENT_MODE,\n KOTLIN_NESTED_COMMENT\n ],\n relevance: 0\n },\n hljs.C_LINE_COMMENT_MODE,\n KOTLIN_NESTED_COMMENT,\n ANNOTATION_USE_SITE,\n ANNOTATION,\n STRING,\n hljs.C_NUMBER_MODE\n ]\n },\n KOTLIN_NESTED_COMMENT\n ]\n },\n {\n className: 'class',\n beginKeywords: 'class interface trait', // remove 'trait' when removed from KEYWORDS\n end: /[:\\{(]|$/,\n excludeEnd: true,\n illegal: 'extends implements',\n contains: [\n {\n beginKeywords: 'public protected internal private constructor'\n },\n hljs.UNDERSCORE_TITLE_MODE,\n {\n className: 'type',\n begin: //,\n excludeBegin: true,\n excludeEnd: true,\n relevance: 0\n },\n {\n className: 'type',\n begin: /[,:]\\s*/,\n end: /[<\\(,]|$/,\n excludeBegin: true,\n returnEnd: true\n },\n ANNOTATION_USE_SITE,\n ANNOTATION\n ]\n },\n STRING,\n {\n className: 'meta',\n begin: \"^#!/usr/bin/env\",\n end: '$',\n illegal: '\\n'\n },\n KOTLIN_NUMBER_MODE\n ]\n };\n}\n\nmodule.exports = kotlin;\n","/**\n * @param {string} value\n * @returns {RegExp}\n * */\n\n/**\n * @param {RegExp | string } re\n * @returns {string}\n */\nfunction source(re) {\n if (!re) return null;\n if (typeof re === \"string\") return re;\n\n return re.source;\n}\n\n/**\n * @param {...(RegExp | string) } args\n * @returns {string}\n */\nfunction concat(...args) {\n const joined = args.map((x) => source(x)).join(\"\");\n return joined;\n}\n\n/*\nLanguage: Markdown\nRequires: xml.js\nAuthor: John Crepezzi \nWebsite: https://daringfireball.net/projects/markdown/\nCategory: common, markup\n*/\n\nfunction markdown(hljs) {\n const INLINE_HTML = {\n begin: /<\\/?[A-Za-z_]/,\n end: '>',\n subLanguage: 'xml',\n relevance: 0\n };\n const HORIZONTAL_RULE = {\n begin: '^[-\\\\*]{3,}',\n end: '$'\n };\n const CODE = {\n className: 'code',\n variants: [\n // TODO: fix to allow these to work with sublanguage also\n {\n begin: '(`{3,})[^`](.|\\\\n)*?\\\\1`*[ ]*'\n },\n {\n begin: '(~{3,})[^~](.|\\\\n)*?\\\\1~*[ ]*'\n },\n // needed to allow markdown as a sublanguage to work\n {\n begin: '```',\n end: '```+[ ]*$'\n },\n {\n begin: '~~~',\n end: '~~~+[ ]*$'\n },\n {\n begin: '`.+?`'\n },\n {\n begin: '(?=^( {4}|\\\\t))',\n // use contains to gobble up multiple lines to allow the block to be whatever size\n // but only have a single open/close tag vs one per line\n contains: [\n {\n begin: '^( {4}|\\\\t)',\n end: '(\\\\n)$'\n }\n ],\n relevance: 0\n }\n ]\n };\n const LIST = {\n className: 'bullet',\n begin: '^[ \\t]*([*+-]|(\\\\d+\\\\.))(?=\\\\s+)',\n end: '\\\\s+',\n excludeEnd: true\n };\n const LINK_REFERENCE = {\n begin: /^\\[[^\\n]+\\]:/,\n returnBegin: true,\n contains: [\n {\n className: 'symbol',\n begin: /\\[/,\n end: /\\]/,\n excludeBegin: true,\n excludeEnd: true\n },\n {\n className: 'link',\n begin: /:\\s*/,\n end: /$/,\n excludeBegin: true\n }\n ]\n };\n const URL_SCHEME = /[A-Za-z][A-Za-z0-9+.-]*/;\n const LINK = {\n variants: [\n // too much like nested array access in so many languages\n // to have any real relevance\n {\n begin: /\\[.+?\\]\\[.*?\\]/,\n relevance: 0\n },\n // popular internet URLs\n {\n begin: /\\[.+?\\]\\(((data|javascript|mailto):|(?:http|ftp)s?:\\/\\/).*?\\)/,\n relevance: 2\n },\n {\n begin: concat(/\\[.+?\\]\\(/, URL_SCHEME, /:\\/\\/.*?\\)/),\n relevance: 2\n },\n // relative urls\n {\n begin: /\\[.+?\\]\\([./?&#].*?\\)/,\n relevance: 1\n },\n // whatever else, lower relevance (might not be a link at all)\n {\n begin: /\\[.+?\\]\\(.*?\\)/,\n relevance: 0\n }\n ],\n returnBegin: true,\n contains: [\n {\n className: 'string',\n relevance: 0,\n begin: '\\\\[',\n end: '\\\\]',\n excludeBegin: true,\n returnEnd: true\n },\n {\n className: 'link',\n relevance: 0,\n begin: '\\\\]\\\\(',\n end: '\\\\)',\n excludeBegin: true,\n excludeEnd: true\n },\n {\n className: 'symbol',\n relevance: 0,\n begin: '\\\\]\\\\[',\n end: '\\\\]',\n excludeBegin: true,\n excludeEnd: true\n }\n ]\n };\n const BOLD = {\n className: 'strong',\n contains: [], // defined later\n variants: [\n {\n begin: /_{2}/,\n end: /_{2}/\n },\n {\n begin: /\\*{2}/,\n end: /\\*{2}/\n }\n ]\n };\n const ITALIC = {\n className: 'emphasis',\n contains: [], // defined later\n variants: [\n {\n begin: /\\*(?!\\*)/,\n end: /\\*/\n },\n {\n begin: /_(?!_)/,\n end: /_/,\n relevance: 0\n }\n ]\n };\n BOLD.contains.push(ITALIC);\n ITALIC.contains.push(BOLD);\n\n let CONTAINABLE = [\n INLINE_HTML,\n LINK\n ];\n\n BOLD.contains = BOLD.contains.concat(CONTAINABLE);\n ITALIC.contains = ITALIC.contains.concat(CONTAINABLE);\n\n CONTAINABLE = CONTAINABLE.concat(BOLD, ITALIC);\n\n const HEADER = {\n className: 'section',\n variants: [\n {\n begin: '^#{1,6}',\n end: '$',\n contains: CONTAINABLE\n },\n {\n begin: '(?=^.+?\\\\n[=-]{2,}$)',\n contains: [\n {\n begin: '^[=-]*$'\n },\n {\n begin: '^',\n end: \"\\\\n\",\n contains: CONTAINABLE\n }\n ]\n }\n ]\n };\n\n const BLOCKQUOTE = {\n className: 'quote',\n begin: '^>\\\\s+',\n contains: CONTAINABLE,\n end: '$'\n };\n\n return {\n name: 'Markdown',\n aliases: [\n 'md',\n 'mkdown',\n 'mkd'\n ],\n contains: [\n HEADER,\n INLINE_HTML,\n LIST,\n BOLD,\n ITALIC,\n BLOCKQUOTE,\n CODE,\n HORIZONTAL_RULE,\n LINK,\n LINK_REFERENCE\n ]\n };\n}\n\nmodule.exports = markdown;\n","/*\nLanguage: Nix\nAuthor: Domen Kožar \nDescription: Nix functional language\nWebsite: http://nixos.org/nix\n*/\n\nfunction nix(hljs) {\n const NIX_KEYWORDS = {\n keyword:\n 'rec with let in inherit assert if else then',\n literal:\n 'true false or and null',\n built_in:\n 'import abort baseNameOf dirOf isNull builtins map removeAttrs throw ' +\n 'toString derivation'\n };\n const ANTIQUOTE = {\n className: 'subst',\n begin: /\\$\\{/,\n end: /\\}/,\n keywords: NIX_KEYWORDS\n };\n const ATTRS = {\n begin: /[a-zA-Z0-9-_]+(\\s*=)/,\n returnBegin: true,\n relevance: 0,\n contains: [\n {\n className: 'attr',\n begin: /\\S+/\n }\n ]\n };\n const STRING = {\n className: 'string',\n contains: [ ANTIQUOTE ],\n variants: [\n {\n begin: \"''\",\n end: \"''\"\n },\n {\n begin: '\"',\n end: '\"'\n }\n ]\n };\n const EXPRESSIONS = [\n hljs.NUMBER_MODE,\n hljs.HASH_COMMENT_MODE,\n hljs.C_BLOCK_COMMENT_MODE,\n STRING,\n ATTRS\n ];\n ANTIQUOTE.contains = EXPRESSIONS;\n return {\n name: 'Nix',\n aliases: [ \"nixos\" ],\n keywords: NIX_KEYWORDS,\n contains: EXPRESSIONS\n };\n}\n\nmodule.exports = nix;\n","/*\nLanguage: PowerShell\nDescription: PowerShell is a task-based command-line shell and scripting language built on .NET.\nAuthor: David Mohundro \nContributors: Nicholas Blumhardt , Victor Zhou , Nicolas Le Gall \nWebsite: https://docs.microsoft.com/en-us/powershell/\n*/\n\nfunction powershell(hljs) {\n const TYPES = [\n \"string\",\n \"char\",\n \"byte\",\n \"int\",\n \"long\",\n \"bool\",\n \"decimal\",\n \"single\",\n \"double\",\n \"DateTime\",\n \"xml\",\n \"array\",\n \"hashtable\",\n \"void\"\n ];\n\n // https://docs.microsoft.com/en-us/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands\n const VALID_VERBS =\n 'Add|Clear|Close|Copy|Enter|Exit|Find|Format|Get|Hide|Join|Lock|' +\n 'Move|New|Open|Optimize|Pop|Push|Redo|Remove|Rename|Reset|Resize|' +\n 'Search|Select|Set|Show|Skip|Split|Step|Switch|Undo|Unlock|' +\n 'Watch|Backup|Checkpoint|Compare|Compress|Convert|ConvertFrom|' +\n 'ConvertTo|Dismount|Edit|Expand|Export|Group|Import|Initialize|' +\n 'Limit|Merge|Mount|Out|Publish|Restore|Save|Sync|Unpublish|Update|' +\n 'Approve|Assert|Build|Complete|Confirm|Deny|Deploy|Disable|Enable|Install|Invoke|' +\n 'Register|Request|Restart|Resume|Start|Stop|Submit|Suspend|Uninstall|' +\n 'Unregister|Wait|Debug|Measure|Ping|Repair|Resolve|Test|Trace|Connect|' +\n 'Disconnect|Read|Receive|Send|Write|Block|Grant|Protect|Revoke|Unblock|' +\n 'Unprotect|Use|ForEach|Sort|Tee|Where';\n\n const COMPARISON_OPERATORS =\n '-and|-as|-band|-bnot|-bor|-bxor|-casesensitive|-ccontains|-ceq|-cge|-cgt|' +\n '-cle|-clike|-clt|-cmatch|-cne|-cnotcontains|-cnotlike|-cnotmatch|-contains|' +\n '-creplace|-csplit|-eq|-exact|-f|-file|-ge|-gt|-icontains|-ieq|-ige|-igt|' +\n '-ile|-ilike|-ilt|-imatch|-in|-ine|-inotcontains|-inotlike|-inotmatch|' +\n '-ireplace|-is|-isnot|-isplit|-join|-le|-like|-lt|-match|-ne|-not|' +\n '-notcontains|-notin|-notlike|-notmatch|-or|-regex|-replace|-shl|-shr|' +\n '-split|-wildcard|-xor';\n\n const KEYWORDS = {\n $pattern: /-?[A-z\\.\\-]+\\b/,\n keyword:\n 'if else foreach return do while until elseif begin for trap data dynamicparam ' +\n 'end break throw param continue finally in switch exit filter try process catch ' +\n 'hidden static parameter',\n // \"echo\" relevance has been set to 0 to avoid auto-detect conflicts with shell transcripts\n built_in:\n 'ac asnp cat cd CFS chdir clc clear clhy cli clp cls clv cnsn compare copy cp ' +\n 'cpi cpp curl cvpa dbp del diff dir dnsn ebp echo|0 epal epcsv epsn erase etsn exsn fc fhx ' +\n 'fl ft fw gal gbp gc gcb gci gcm gcs gdr gerr ghy gi gin gjb gl gm gmo gp gps gpv group ' +\n 'gsn gsnp gsv gtz gu gv gwmi h history icm iex ihy ii ipal ipcsv ipmo ipsn irm ise iwmi ' +\n 'iwr kill lp ls man md measure mi mount move mp mv nal ndr ni nmo npssc nsn nv ogv oh ' +\n 'popd ps pushd pwd r rbp rcjb rcsn rd rdr ren ri rjb rm rmdir rmo rni rnp rp rsn rsnp ' +\n 'rujb rv rvpa rwmi sajb sal saps sasv sbp sc scb select set shcm si sl sleep sls sort sp ' +\n 'spjb spps spsv start stz sujb sv swmi tee trcm type wget where wjb write'\n // TODO: 'validate[A-Z]+' can't work in keywords\n };\n\n const TITLE_NAME_RE = /\\w[\\w\\d]*((-)[\\w\\d]+)*/;\n\n const BACKTICK_ESCAPE = {\n begin: '`[\\\\s\\\\S]',\n relevance: 0\n };\n\n const VAR = {\n className: 'variable',\n variants: [\n {\n begin: /\\$\\B/\n },\n {\n className: 'keyword',\n begin: /\\$this/\n },\n {\n begin: /\\$[\\w\\d][\\w\\d_:]*/\n }\n ]\n };\n\n const LITERAL = {\n className: 'literal',\n begin: /\\$(null|true|false)\\b/\n };\n\n const QUOTE_STRING = {\n className: \"string\",\n variants: [\n {\n begin: /\"/,\n end: /\"/\n },\n {\n begin: /@\"/,\n end: /^\"@/\n }\n ],\n contains: [\n BACKTICK_ESCAPE,\n VAR,\n {\n className: 'variable',\n begin: /\\$[A-z]/,\n end: /[^A-z]/\n }\n ]\n };\n\n const APOS_STRING = {\n className: 'string',\n variants: [\n {\n begin: /'/,\n end: /'/\n },\n {\n begin: /@'/,\n end: /^'@/\n }\n ]\n };\n\n const PS_HELPTAGS = {\n className: \"doctag\",\n variants: [\n /* no paramater help tags */\n {\n begin: /\\.(synopsis|description|example|inputs|outputs|notes|link|component|role|functionality)/\n },\n /* one parameter help tags */\n {\n begin: /\\.(parameter|forwardhelptargetname|forwardhelpcategory|remotehelprunspace|externalhelp)\\s+\\S+/\n }\n ]\n };\n\n const PS_COMMENT = hljs.inherit(\n hljs.COMMENT(null, null),\n {\n variants: [\n /* single-line comment */\n {\n begin: /#/,\n end: /$/\n },\n /* multi-line comment */\n {\n begin: /<#/,\n end: /#>/\n }\n ],\n contains: [ PS_HELPTAGS ]\n }\n );\n\n const CMDLETS = {\n className: 'built_in',\n variants: [\n {\n begin: '('.concat(VALID_VERBS, ')+(-)[\\\\w\\\\d]+')\n }\n ]\n };\n\n const PS_CLASS = {\n className: 'class',\n beginKeywords: 'class enum',\n end: /\\s*[{]/,\n excludeEnd: true,\n relevance: 0,\n contains: [ hljs.TITLE_MODE ]\n };\n\n const PS_FUNCTION = {\n className: 'function',\n begin: /function\\s+/,\n end: /\\s*\\{|$/,\n excludeEnd: true,\n returnBegin: true,\n relevance: 0,\n contains: [\n {\n begin: \"function\",\n relevance: 0,\n className: \"keyword\"\n },\n {\n className: \"title\",\n begin: TITLE_NAME_RE,\n relevance: 0\n },\n {\n begin: /\\(/,\n end: /\\)/,\n className: \"params\",\n relevance: 0,\n contains: [ VAR ]\n }\n // CMDLETS\n ]\n };\n\n // Using statment, plus type, plus assembly name.\n const PS_USING = {\n begin: /using\\s/,\n end: /$/,\n returnBegin: true,\n contains: [\n QUOTE_STRING,\n APOS_STRING,\n {\n className: 'keyword',\n begin: /(using|assembly|command|module|namespace|type)/\n }\n ]\n };\n\n // Comperison operators & function named parameters.\n const PS_ARGUMENTS = {\n variants: [\n // PS literals are pretty verbose so it's a good idea to accent them a bit.\n {\n className: 'operator',\n begin: '('.concat(COMPARISON_OPERATORS, ')\\\\b')\n },\n {\n className: 'literal',\n begin: /(-)[\\w\\d]+/,\n relevance: 0\n }\n ]\n };\n\n const HASH_SIGNS = {\n className: 'selector-tag',\n begin: /@\\B/,\n relevance: 0\n };\n\n // It's a very general rule so I'll narrow it a bit with some strict boundaries\n // to avoid any possible false-positive collisions!\n const PS_METHODS = {\n className: 'function',\n begin: /\\[.*\\]\\s*[\\w]+[ ]??\\(/,\n end: /$/,\n returnBegin: true,\n relevance: 0,\n contains: [\n {\n className: 'keyword',\n begin: '('.concat(\n KEYWORDS.keyword.toString().replace(/\\s/g, '|'\n ), ')\\\\b'),\n endsParent: true,\n relevance: 0\n },\n hljs.inherit(hljs.TITLE_MODE, {\n endsParent: true\n })\n ]\n };\n\n const GENTLEMANS_SET = [\n // STATIC_MEMBER,\n PS_METHODS,\n PS_COMMENT,\n BACKTICK_ESCAPE,\n hljs.NUMBER_MODE,\n QUOTE_STRING,\n APOS_STRING,\n // PS_NEW_OBJECT_TYPE,\n CMDLETS,\n VAR,\n LITERAL,\n HASH_SIGNS\n ];\n\n const PS_TYPE = {\n begin: /\\[/,\n end: /\\]/,\n excludeBegin: true,\n excludeEnd: true,\n relevance: 0,\n contains: [].concat(\n 'self',\n GENTLEMANS_SET,\n {\n begin: \"(\" + TYPES.join(\"|\") + \")\",\n className: \"built_in\",\n relevance: 0\n },\n {\n className: 'type',\n begin: /[\\.\\w\\d]+/,\n relevance: 0\n }\n )\n };\n\n PS_METHODS.contains.unshift(PS_TYPE);\n\n return {\n name: 'PowerShell',\n aliases: [\n \"ps\",\n \"ps1\"\n ],\n case_insensitive: true,\n keywords: KEYWORDS,\n contains: GENTLEMANS_SET.concat(\n PS_CLASS,\n PS_FUNCTION,\n PS_USING,\n PS_ARGUMENTS,\n PS_TYPE\n )\n };\n}\n\nmodule.exports = powershell;\n","/*\nLanguage: .properties\nContributors: Valentin Aitken , Egor Rogov \nWebsite: https://en.wikipedia.org/wiki/.properties\nCategory: common, config\n*/\n\nfunction properties(hljs) {\n\n // whitespaces: space, tab, formfeed\n var WS0 = '[ \\\\t\\\\f]*';\n var WS1 = '[ \\\\t\\\\f]+';\n // delimiter\n var EQUAL_DELIM = WS0+'[:=]'+WS0;\n var WS_DELIM = WS1;\n var DELIM = '(' + EQUAL_DELIM + '|' + WS_DELIM + ')';\n var KEY_ALPHANUM = '([^\\\\\\\\\\\\W:= \\\\t\\\\f\\\\n]|\\\\\\\\.)+';\n var KEY_OTHER = '([^\\\\\\\\:= \\\\t\\\\f\\\\n]|\\\\\\\\.)+';\n\n var DELIM_AND_VALUE = {\n // skip DELIM\n end: DELIM,\n relevance: 0,\n starts: {\n // value: everything until end of line (again, taking into account backslashes)\n className: 'string',\n end: /$/,\n relevance: 0,\n contains: [\n { begin: '\\\\\\\\\\\\\\\\'},\n { begin: '\\\\\\\\\\\\n' }\n ]\n }\n };\n\n return {\n name: '.properties',\n case_insensitive: true,\n illegal: /\\S/,\n contains: [\n hljs.COMMENT('^\\\\s*[!#]', '$'),\n // key: everything until whitespace or = or : (taking into account backslashes)\n // case of a \"normal\" key\n {\n returnBegin: true,\n variants: [\n { begin: KEY_ALPHANUM + EQUAL_DELIM, relevance: 1 },\n { begin: KEY_ALPHANUM + WS_DELIM, relevance: 0 }\n ],\n contains: [\n {\n className: 'attr',\n begin: KEY_ALPHANUM,\n endsParent: true,\n relevance: 0\n }\n ],\n starts: DELIM_AND_VALUE\n },\n // case of key containing non-alphanumeric chars => relevance = 0\n {\n begin: KEY_OTHER + DELIM,\n returnBegin: true,\n relevance: 0,\n contains: [\n {\n className: 'meta',\n begin: KEY_OTHER,\n endsParent: true,\n relevance: 0\n }\n ],\n starts: DELIM_AND_VALUE\n },\n // case of an empty key\n {\n className: 'attr',\n relevance: 0,\n begin: KEY_OTHER + WS0 + '$'\n }\n ]\n };\n}\n\nmodule.exports = properties;\n","/**\n * @param {string} value\n * @returns {RegExp}\n * */\n\n/**\n * @param {RegExp | string } re\n * @returns {string}\n */\nfunction source(re) {\n if (!re) return null;\n if (typeof re === \"string\") return re;\n\n return re.source;\n}\n\n/**\n * @param {RegExp | string } re\n * @returns {string}\n */\nfunction lookahead(re) {\n return concat('(?=', re, ')');\n}\n\n/**\n * @param {...(RegExp | string) } args\n * @returns {string}\n */\nfunction concat(...args) {\n const joined = args.map((x) => source(x)).join(\"\");\n return joined;\n}\n\n/*\nLanguage: Ruby\nDescription: Ruby is a dynamic, open source programming language with a focus on simplicity and productivity.\nWebsite: https://www.ruby-lang.org/\nAuthor: Anton Kovalyov \nContributors: Peter Leonov , Vasily Polovnyov , Loren Segal , Pascal Hurni , Cedric Sohrauer \nCategory: common\n*/\n\nfunction ruby(hljs) {\n const RUBY_METHOD_RE = '([a-zA-Z_]\\\\w*[!?=]?|[-+~]@|<<|>>|=~|===?|<=>|[<>]=?|\\\\*\\\\*|[-/+%^&*~`|]|\\\\[\\\\]=?)';\n const RUBY_KEYWORDS = {\n keyword:\n 'and then defined module in return redo if BEGIN retry end for self when ' +\n 'next until do begin unless END rescue else break undef not super class case ' +\n 'require yield alias while ensure elsif or include attr_reader attr_writer attr_accessor ' +\n '__FILE__',\n built_in: 'proc lambda',\n literal:\n 'true false nil'\n };\n const YARDOCTAG = {\n className: 'doctag',\n begin: '@[A-Za-z]+'\n };\n const IRB_OBJECT = {\n begin: '#<',\n end: '>'\n };\n const COMMENT_MODES = [\n hljs.COMMENT(\n '#',\n '$',\n {\n contains: [ YARDOCTAG ]\n }\n ),\n hljs.COMMENT(\n '^=begin',\n '^=end',\n {\n contains: [ YARDOCTAG ],\n relevance: 10\n }\n ),\n hljs.COMMENT('^__END__', '\\\\n$')\n ];\n const SUBST = {\n className: 'subst',\n begin: /#\\{/,\n end: /\\}/,\n keywords: RUBY_KEYWORDS\n };\n const STRING = {\n className: 'string',\n contains: [\n hljs.BACKSLASH_ESCAPE,\n SUBST\n ],\n variants: [\n {\n begin: /'/,\n end: /'/\n },\n {\n begin: /\"/,\n end: /\"/\n },\n {\n begin: /`/,\n end: /`/\n },\n {\n begin: /%[qQwWx]?\\(/,\n end: /\\)/\n },\n {\n begin: /%[qQwWx]?\\[/,\n end: /\\]/\n },\n {\n begin: /%[qQwWx]?\\{/,\n end: /\\}/\n },\n {\n begin: /%[qQwWx]?/\n },\n {\n begin: /%[qQwWx]?\\//,\n end: /\\//\n },\n {\n begin: /%[qQwWx]?%/,\n end: /%/\n },\n {\n begin: /%[qQwWx]?-/,\n end: /-/\n },\n {\n begin: /%[qQwWx]?\\|/,\n end: /\\|/\n },\n // in the following expressions, \\B in the beginning suppresses recognition of ?-sequences\n // where ? is the last character of a preceding identifier, as in: `func?4`\n {\n begin: /\\B\\?(\\\\\\d{1,3})/\n },\n {\n begin: /\\B\\?(\\\\x[A-Fa-f0-9]{1,2})/\n },\n {\n begin: /\\B\\?(\\\\u\\{?[A-Fa-f0-9]{1,6}\\}?)/\n },\n {\n begin: /\\B\\?(\\\\M-\\\\C-|\\\\M-\\\\c|\\\\c\\\\M-|\\\\M-|\\\\C-\\\\M-)[\\x20-\\x7e]/\n },\n {\n begin: /\\B\\?\\\\(c|C-)[\\x20-\\x7e]/\n },\n {\n begin: /\\B\\?\\\\?\\S/\n },\n { // heredocs\n begin: /<<[-~]?'?(\\w+)\\n(?:[^\\n]*\\n)*?\\s*\\1\\b/,\n returnBegin: true,\n contains: [\n {\n begin: /<<[-~]?'?/\n },\n hljs.END_SAME_AS_BEGIN({\n begin: /(\\w+)/,\n end: /(\\w+)/,\n contains: [\n hljs.BACKSLASH_ESCAPE,\n SUBST\n ]\n })\n ]\n }\n ]\n };\n\n // Ruby syntax is underdocumented, but this grammar seems to be accurate\n // as of version 2.7.2 (confirmed with (irb and `Ripper.sexp(...)`)\n // https://docs.ruby-lang.org/en/2.7.0/doc/syntax/literals_rdoc.html#label-Numbers\n const decimal = '[1-9](_?[0-9])*|0';\n const digits = '[0-9](_?[0-9])*';\n const NUMBER = {\n className: 'number',\n relevance: 0,\n variants: [\n // decimal integer/float, optionally exponential or rational, optionally imaginary\n {\n begin: `\\\\b(${decimal})(\\\\.(${digits}))?([eE][+-]?(${digits})|r)?i?\\\\b`\n },\n\n // explicit decimal/binary/octal/hexadecimal integer,\n // optionally rational and/or imaginary\n {\n begin: \"\\\\b0[dD][0-9](_?[0-9])*r?i?\\\\b\"\n },\n {\n begin: \"\\\\b0[bB][0-1](_?[0-1])*r?i?\\\\b\"\n },\n {\n begin: \"\\\\b0[oO][0-7](_?[0-7])*r?i?\\\\b\"\n },\n {\n begin: \"\\\\b0[xX][0-9a-fA-F](_?[0-9a-fA-F])*r?i?\\\\b\"\n },\n\n // 0-prefixed implicit octal integer, optionally rational and/or imaginary\n {\n begin: \"\\\\b0(_?[0-7])+r?i?\\\\b\"\n }\n ]\n };\n\n const PARAMS = {\n className: 'params',\n begin: '\\\\(',\n end: '\\\\)',\n endsParent: true,\n keywords: RUBY_KEYWORDS\n };\n\n const RUBY_DEFAULT_CONTAINS = [\n STRING,\n {\n className: 'class',\n beginKeywords: 'class module',\n end: '$|;',\n illegal: /=/,\n contains: [\n hljs.inherit(hljs.TITLE_MODE, {\n begin: '[A-Za-z_]\\\\w*(::\\\\w+)*(\\\\?|!)?'\n }),\n {\n begin: '<\\\\s*',\n contains: [\n {\n begin: '(' + hljs.IDENT_RE + '::)?' + hljs.IDENT_RE,\n // we already get points for <, we don't need poitns\n // for the name also\n relevance: 0\n }\n ]\n }\n ].concat(COMMENT_MODES)\n },\n {\n className: 'function',\n // def method_name(\n // def method_name;\n // def method_name (end of line)\n begin: concat(/def\\s+/, lookahead(RUBY_METHOD_RE + \"\\\\s*(\\\\(|;|$)\")),\n relevance: 0, // relevance comes from kewords\n keywords: \"def\",\n end: '$|;',\n contains: [\n hljs.inherit(hljs.TITLE_MODE, {\n begin: RUBY_METHOD_RE\n }),\n PARAMS\n ].concat(COMMENT_MODES)\n },\n {\n // swallow namespace qualifiers before symbols\n begin: hljs.IDENT_RE + '::'\n },\n {\n className: 'symbol',\n begin: hljs.UNDERSCORE_IDENT_RE + '(!|\\\\?)?:',\n relevance: 0\n },\n {\n className: 'symbol',\n begin: ':(?!\\\\s)',\n contains: [\n STRING,\n {\n begin: RUBY_METHOD_RE\n }\n ],\n relevance: 0\n },\n NUMBER,\n {\n // negative-look forward attemps to prevent false matches like:\n // @ident@ or $ident$ that might indicate this is not ruby at all\n className: \"variable\",\n begin: '(\\\\$\\\\W)|((\\\\$|@@?)(\\\\w+))(?=[^@$?])' + `(?![A-Za-z])(?![@$?'])`\n },\n {\n className: 'params',\n begin: /\\|/,\n end: /\\|/,\n relevance: 0, // this could be a lot of things (in other languages) other than params\n keywords: RUBY_KEYWORDS\n },\n { // regexp container\n begin: '(' + hljs.RE_STARTERS_RE + '|unless)\\\\s*',\n keywords: 'unless',\n contains: [\n {\n className: 'regexp',\n contains: [\n hljs.BACKSLASH_ESCAPE,\n SUBST\n ],\n illegal: /\\n/,\n variants: [\n {\n begin: '/',\n end: '/[a-z]*'\n },\n {\n begin: /%r\\{/,\n end: /\\}[a-z]*/\n },\n {\n begin: '%r\\\\(',\n end: '\\\\)[a-z]*'\n },\n {\n begin: '%r!',\n end: '![a-z]*'\n },\n {\n begin: '%r\\\\[',\n end: '\\\\][a-z]*'\n }\n ]\n }\n ].concat(IRB_OBJECT, COMMENT_MODES),\n relevance: 0\n }\n ].concat(IRB_OBJECT, COMMENT_MODES);\n\n SUBST.contains = RUBY_DEFAULT_CONTAINS;\n PARAMS.contains = RUBY_DEFAULT_CONTAINS;\n\n // >>\n // ?>\n const SIMPLE_PROMPT = \"[>?]>\";\n // irb(main):001:0>\n const DEFAULT_PROMPT = \"[\\\\w#]+\\\\(\\\\w+\\\\):\\\\d+:\\\\d+>\";\n const RVM_PROMPT = \"(\\\\w+-)?\\\\d+\\\\.\\\\d+\\\\.\\\\d+(p\\\\d+)?[^\\\\d][^>]+>\";\n\n const IRB_DEFAULT = [\n {\n begin: /^\\s*=>/,\n starts: {\n end: '$',\n contains: RUBY_DEFAULT_CONTAINS\n }\n },\n {\n className: 'meta',\n begin: '^(' + SIMPLE_PROMPT + \"|\" + DEFAULT_PROMPT + '|' + RVM_PROMPT + ')(?=[ ])',\n starts: {\n end: '$',\n contains: RUBY_DEFAULT_CONTAINS\n }\n }\n ];\n\n COMMENT_MODES.unshift(IRB_OBJECT);\n\n return {\n name: 'Ruby',\n aliases: [\n 'rb',\n 'gemspec',\n 'podspec',\n 'thor',\n 'irb'\n ],\n keywords: RUBY_KEYWORDS,\n illegal: /\\/\\*/,\n contains: [\n hljs.SHEBANG({\n binary: \"ruby\"\n })\n ]\n .concat(IRB_DEFAULT)\n .concat(COMMENT_MODES)\n .concat(RUBY_DEFAULT_CONTAINS)\n };\n}\n\nmodule.exports = ruby;\n","/*\nLanguage: Scala\nCategory: functional\nAuthor: Jan Berkel \nContributors: Erik Osheim \nWebsite: https://www.scala-lang.org\n*/\n\nfunction scala(hljs) {\n const ANNOTATION = {\n className: 'meta',\n begin: '@[A-Za-z]+'\n };\n\n // used in strings for escaping/interpolation/substitution\n const SUBST = {\n className: 'subst',\n variants: [\n {\n begin: '\\\\$[A-Za-z0-9_]+'\n },\n {\n begin: /\\$\\{/,\n end: /\\}/\n }\n ]\n };\n\n const STRING = {\n className: 'string',\n variants: [\n {\n begin: '\"\"\"',\n end: '\"\"\"'\n },\n {\n begin: '\"',\n end: '\"',\n illegal: '\\\\n',\n contains: [ hljs.BACKSLASH_ESCAPE ]\n },\n {\n begin: '[a-z]+\"',\n end: '\"',\n illegal: '\\\\n',\n contains: [\n hljs.BACKSLASH_ESCAPE,\n SUBST\n ]\n },\n {\n className: 'string',\n begin: '[a-z]+\"\"\"',\n end: '\"\"\"',\n contains: [ SUBST ],\n relevance: 10\n }\n ]\n\n };\n\n const SYMBOL = {\n className: 'symbol',\n begin: '\\'\\\\w[\\\\w\\\\d_]*(?!\\')'\n };\n\n const TYPE = {\n className: 'type',\n begin: '\\\\b[A-Z][A-Za-z0-9_]*',\n relevance: 0\n };\n\n const NAME = {\n className: 'title',\n begin: /[^0-9\\n\\t \"'(),.`{}\\[\\]:;][^\\n\\t \"'(),.`{}\\[\\]:;]+|[^0-9\\n\\t \"'(),.`{}\\[\\]:;=]/,\n relevance: 0\n };\n\n const CLASS = {\n className: 'class',\n beginKeywords: 'class object trait type',\n end: /[:={\\[\\n;]/,\n excludeEnd: true,\n contains: [\n hljs.C_LINE_COMMENT_MODE,\n hljs.C_BLOCK_COMMENT_MODE,\n {\n beginKeywords: 'extends with',\n relevance: 10\n },\n {\n begin: /\\[/,\n end: /\\]/,\n excludeBegin: true,\n excludeEnd: true,\n relevance: 0,\n contains: [ TYPE ]\n },\n {\n className: 'params',\n begin: /\\(/,\n end: /\\)/,\n excludeBegin: true,\n excludeEnd: true,\n relevance: 0,\n contains: [ TYPE ]\n },\n NAME\n ]\n };\n\n const METHOD = {\n className: 'function',\n beginKeywords: 'def',\n end: /[:={\\[(\\n;]/,\n excludeEnd: true,\n contains: [ NAME ]\n };\n\n return {\n name: 'Scala',\n keywords: {\n literal: 'true false null',\n keyword: 'type yield lazy override def with val var sealed abstract private trait object if forSome for while throw finally protected extends import final return else break new catch super class case package default try this match continue throws implicit'\n },\n contains: [\n hljs.C_LINE_COMMENT_MODE,\n hljs.C_BLOCK_COMMENT_MODE,\n STRING,\n SYMBOL,\n TYPE,\n METHOD,\n CLASS,\n hljs.C_NUMBER_MODE,\n ANNOTATION\n ]\n };\n}\n\nmodule.exports = scala;\n","/*\nLanguage: Shell Session\nRequires: bash.js\nAuthor: TSUYUSATO Kitsune \nCategory: common\nAudit: 2020\n*/\n\n/** @type LanguageFn */\nfunction shell(hljs) {\n return {\n name: 'Shell Session',\n aliases: [ 'console' ],\n contains: [\n {\n className: 'meta',\n // We cannot add \\s (spaces) in the regular expression otherwise it will be too broad and produce unexpected result.\n // For instance, in the following example, it would match \"echo /path/to/home >\" as a prompt:\n // echo /path/to/home > t.exe\n begin: /^\\s{0,3}[/~\\w\\d[\\]()@-]*[>%$#]/,\n starts: {\n end: /[^\\\\](?=\\s*$)/,\n subLanguage: 'bash'\n }\n }\n ]\n };\n}\n\nmodule.exports = shell;\n","/**\n * @param {string} value\n * @returns {RegExp}\n * */\n\n/**\n * @param {RegExp | string } re\n * @returns {string}\n */\nfunction source(re) {\n if (!re) return null;\n if (typeof re === \"string\") return re;\n\n return re.source;\n}\n\n/**\n * @param {...(RegExp | string) } args\n * @returns {string}\n */\nfunction concat(...args) {\n const joined = args.map((x) => source(x)).join(\"\");\n return joined;\n}\n\n/**\n * Any of the passed expresssions may match\n *\n * Creates a huge this | this | that | that match\n * @param {(RegExp | string)[] } args\n * @returns {string}\n */\nfunction either(...args) {\n const joined = '(' + args.map((x) => source(x)).join(\"|\") + \")\";\n return joined;\n}\n\n/*\n Language: SQL\n Website: https://en.wikipedia.org/wiki/SQL\n Category: common, database\n */\n\nfunction sql(hljs) {\n const COMMENT_MODE = hljs.COMMENT('--', '$');\n const STRING = {\n className: 'string',\n variants: [\n {\n begin: /'/,\n end: /'/,\n contains: [\n {begin: /''/ }\n ]\n }\n ]\n };\n const QUOTED_IDENTIFIER = {\n begin: /\"/,\n end: /\"/,\n contains: [ { begin: /\"\"/ } ]\n };\n\n const LITERALS = [\n \"true\",\n \"false\",\n // Not sure it's correct to call NULL literal, and clauses like IS [NOT] NULL look strange that way.\n // \"null\",\n \"unknown\"\n ];\n\n const MULTI_WORD_TYPES = [\n \"double precision\",\n \"large object\",\n \"with timezone\",\n \"without timezone\"\n ];\n\n const TYPES = [\n 'bigint',\n 'binary',\n 'blob',\n 'boolean',\n 'char',\n 'character',\n 'clob',\n 'date',\n 'dec',\n 'decfloat',\n 'decimal',\n 'float',\n 'int',\n 'integer',\n 'interval',\n 'nchar',\n 'nclob',\n 'national',\n 'numeric',\n 'real',\n 'row',\n 'smallint',\n 'time',\n 'timestamp',\n 'varchar',\n 'varying', // modifier (character varying)\n 'varbinary'\n ];\n\n const NON_RESERVED_WORDS = [\n \"add\",\n \"asc\",\n \"collation\",\n \"desc\",\n \"final\",\n \"first\",\n \"last\",\n \"view\"\n ];\n\n // https://jakewheat.github.io/sql-overview/sql-2016-foundation-grammar.html#reserved-word\n const RESERVED_WORDS = [\n \"abs\",\n \"acos\",\n \"all\",\n \"allocate\",\n \"alter\",\n \"and\",\n \"any\",\n \"are\",\n \"array\",\n \"array_agg\",\n \"array_max_cardinality\",\n \"as\",\n \"asensitive\",\n \"asin\",\n \"asymmetric\",\n \"at\",\n \"atan\",\n \"atomic\",\n \"authorization\",\n \"avg\",\n \"begin\",\n \"begin_frame\",\n \"begin_partition\",\n \"between\",\n \"bigint\",\n \"binary\",\n \"blob\",\n \"boolean\",\n \"both\",\n \"by\",\n \"call\",\n \"called\",\n \"cardinality\",\n \"cascaded\",\n \"case\",\n \"cast\",\n \"ceil\",\n \"ceiling\",\n \"char\",\n \"char_length\",\n \"character\",\n \"character_length\",\n \"check\",\n \"classifier\",\n \"clob\",\n \"close\",\n \"coalesce\",\n \"collate\",\n \"collect\",\n \"column\",\n \"commit\",\n \"condition\",\n \"connect\",\n \"constraint\",\n \"contains\",\n \"convert\",\n \"copy\",\n \"corr\",\n \"corresponding\",\n \"cos\",\n \"cosh\",\n \"count\",\n \"covar_pop\",\n \"covar_samp\",\n \"create\",\n \"cross\",\n \"cube\",\n \"cume_dist\",\n \"current\",\n \"current_catalog\",\n \"current_date\",\n \"current_default_transform_group\",\n \"current_path\",\n \"current_role\",\n \"current_row\",\n \"current_schema\",\n \"current_time\",\n \"current_timestamp\",\n \"current_path\",\n \"current_role\",\n \"current_transform_group_for_type\",\n \"current_user\",\n \"cursor\",\n \"cycle\",\n \"date\",\n \"day\",\n \"deallocate\",\n \"dec\",\n \"decimal\",\n \"decfloat\",\n \"declare\",\n \"default\",\n \"define\",\n \"delete\",\n \"dense_rank\",\n \"deref\",\n \"describe\",\n \"deterministic\",\n \"disconnect\",\n \"distinct\",\n \"double\",\n \"drop\",\n \"dynamic\",\n \"each\",\n \"element\",\n \"else\",\n \"empty\",\n \"end\",\n \"end_frame\",\n \"end_partition\",\n \"end-exec\",\n \"equals\",\n \"escape\",\n \"every\",\n \"except\",\n \"exec\",\n \"execute\",\n \"exists\",\n \"exp\",\n \"external\",\n \"extract\",\n \"false\",\n \"fetch\",\n \"filter\",\n \"first_value\",\n \"float\",\n \"floor\",\n \"for\",\n \"foreign\",\n \"frame_row\",\n \"free\",\n \"from\",\n \"full\",\n \"function\",\n \"fusion\",\n \"get\",\n \"global\",\n \"grant\",\n \"group\",\n \"grouping\",\n \"groups\",\n \"having\",\n \"hold\",\n \"hour\",\n \"identity\",\n \"in\",\n \"indicator\",\n \"initial\",\n \"inner\",\n \"inout\",\n \"insensitive\",\n \"insert\",\n \"int\",\n \"integer\",\n \"intersect\",\n \"intersection\",\n \"interval\",\n \"into\",\n \"is\",\n \"join\",\n \"json_array\",\n \"json_arrayagg\",\n \"json_exists\",\n \"json_object\",\n \"json_objectagg\",\n \"json_query\",\n \"json_table\",\n \"json_table_primitive\",\n \"json_value\",\n \"lag\",\n \"language\",\n \"large\",\n \"last_value\",\n \"lateral\",\n \"lead\",\n \"leading\",\n \"left\",\n \"like\",\n \"like_regex\",\n \"listagg\",\n \"ln\",\n \"local\",\n \"localtime\",\n \"localtimestamp\",\n \"log\",\n \"log10\",\n \"lower\",\n \"match\",\n \"match_number\",\n \"match_recognize\",\n \"matches\",\n \"max\",\n \"member\",\n \"merge\",\n \"method\",\n \"min\",\n \"minute\",\n \"mod\",\n \"modifies\",\n \"module\",\n \"month\",\n \"multiset\",\n \"national\",\n \"natural\",\n \"nchar\",\n \"nclob\",\n \"new\",\n \"no\",\n \"none\",\n \"normalize\",\n \"not\",\n \"nth_value\",\n \"ntile\",\n \"null\",\n \"nullif\",\n \"numeric\",\n \"octet_length\",\n \"occurrences_regex\",\n \"of\",\n \"offset\",\n \"old\",\n \"omit\",\n \"on\",\n \"one\",\n \"only\",\n \"open\",\n \"or\",\n \"order\",\n \"out\",\n \"outer\",\n \"over\",\n \"overlaps\",\n \"overlay\",\n \"parameter\",\n \"partition\",\n \"pattern\",\n \"per\",\n \"percent\",\n \"percent_rank\",\n \"percentile_cont\",\n \"percentile_disc\",\n \"period\",\n \"portion\",\n \"position\",\n \"position_regex\",\n \"power\",\n \"precedes\",\n \"precision\",\n \"prepare\",\n \"primary\",\n \"procedure\",\n \"ptf\",\n \"range\",\n \"rank\",\n \"reads\",\n \"real\",\n \"recursive\",\n \"ref\",\n \"references\",\n \"referencing\",\n \"regr_avgx\",\n \"regr_avgy\",\n \"regr_count\",\n \"regr_intercept\",\n \"regr_r2\",\n \"regr_slope\",\n \"regr_sxx\",\n \"regr_sxy\",\n \"regr_syy\",\n \"release\",\n \"result\",\n \"return\",\n \"returns\",\n \"revoke\",\n \"right\",\n \"rollback\",\n \"rollup\",\n \"row\",\n \"row_number\",\n \"rows\",\n \"running\",\n \"savepoint\",\n \"scope\",\n \"scroll\",\n \"search\",\n \"second\",\n \"seek\",\n \"select\",\n \"sensitive\",\n \"session_user\",\n \"set\",\n \"show\",\n \"similar\",\n \"sin\",\n \"sinh\",\n \"skip\",\n \"smallint\",\n \"some\",\n \"specific\",\n \"specifictype\",\n \"sql\",\n \"sqlexception\",\n \"sqlstate\",\n \"sqlwarning\",\n \"sqrt\",\n \"start\",\n \"static\",\n \"stddev_pop\",\n \"stddev_samp\",\n \"submultiset\",\n \"subset\",\n \"substring\",\n \"substring_regex\",\n \"succeeds\",\n \"sum\",\n \"symmetric\",\n \"system\",\n \"system_time\",\n \"system_user\",\n \"table\",\n \"tablesample\",\n \"tan\",\n \"tanh\",\n \"then\",\n \"time\",\n \"timestamp\",\n \"timezone_hour\",\n \"timezone_minute\",\n \"to\",\n \"trailing\",\n \"translate\",\n \"translate_regex\",\n \"translation\",\n \"treat\",\n \"trigger\",\n \"trim\",\n \"trim_array\",\n \"true\",\n \"truncate\",\n \"uescape\",\n \"union\",\n \"unique\",\n \"unknown\",\n \"unnest\",\n \"update \",\n \"upper\",\n \"user\",\n \"using\",\n \"value\",\n \"values\",\n \"value_of\",\n \"var_pop\",\n \"var_samp\",\n \"varbinary\",\n \"varchar\",\n \"varying\",\n \"versioning\",\n \"when\",\n \"whenever\",\n \"where\",\n \"width_bucket\",\n \"window\",\n \"with\",\n \"within\",\n \"without\",\n \"year\",\n ];\n\n // these are reserved words we have identified to be functions\n // and should only be highlighted in a dispatch-like context\n // ie, array_agg(...), etc.\n const RESERVED_FUNCTIONS = [\n \"abs\",\n \"acos\",\n \"array_agg\",\n \"asin\",\n \"atan\",\n \"avg\",\n \"cast\",\n \"ceil\",\n \"ceiling\",\n \"coalesce\",\n \"corr\",\n \"cos\",\n \"cosh\",\n \"count\",\n \"covar_pop\",\n \"covar_samp\",\n \"cume_dist\",\n \"dense_rank\",\n \"deref\",\n \"element\",\n \"exp\",\n \"extract\",\n \"first_value\",\n \"floor\",\n \"json_array\",\n \"json_arrayagg\",\n \"json_exists\",\n \"json_object\",\n \"json_objectagg\",\n \"json_query\",\n \"json_table\",\n \"json_table_primitive\",\n \"json_value\",\n \"lag\",\n \"last_value\",\n \"lead\",\n \"listagg\",\n \"ln\",\n \"log\",\n \"log10\",\n \"lower\",\n \"max\",\n \"min\",\n \"mod\",\n \"nth_value\",\n \"ntile\",\n \"nullif\",\n \"percent_rank\",\n \"percentile_cont\",\n \"percentile_disc\",\n \"position\",\n \"position_regex\",\n \"power\",\n \"rank\",\n \"regr_avgx\",\n \"regr_avgy\",\n \"regr_count\",\n \"regr_intercept\",\n \"regr_r2\",\n \"regr_slope\",\n \"regr_sxx\",\n \"regr_sxy\",\n \"regr_syy\",\n \"row_number\",\n \"sin\",\n \"sinh\",\n \"sqrt\",\n \"stddev_pop\",\n \"stddev_samp\",\n \"substring\",\n \"substring_regex\",\n \"sum\",\n \"tan\",\n \"tanh\",\n \"translate\",\n \"translate_regex\",\n \"treat\",\n \"trim\",\n \"trim_array\",\n \"unnest\",\n \"upper\",\n \"value_of\",\n \"var_pop\",\n \"var_samp\",\n \"width_bucket\",\n ];\n\n // these functions can\n const POSSIBLE_WITHOUT_PARENS = [\n \"current_catalog\",\n \"current_date\",\n \"current_default_transform_group\",\n \"current_path\",\n \"current_role\",\n \"current_schema\",\n \"current_transform_group_for_type\",\n \"current_user\",\n \"session_user\",\n \"system_time\",\n \"system_user\",\n \"current_time\",\n \"localtime\",\n \"current_timestamp\",\n \"localtimestamp\"\n ];\n\n // those exist to boost relevance making these very\n // \"SQL like\" keyword combos worth +1 extra relevance\n const COMBOS = [\n \"create table\",\n \"insert into\",\n \"primary key\",\n \"foreign key\",\n \"not null\",\n \"alter table\",\n \"add constraint\",\n \"grouping sets\",\n \"on overflow\",\n \"character set\",\n \"respect nulls\",\n \"ignore nulls\",\n \"nulls first\",\n \"nulls last\",\n \"depth first\",\n \"breadth first\"\n ];\n\n const FUNCTIONS = RESERVED_FUNCTIONS;\n\n const KEYWORDS = [...RESERVED_WORDS, ...NON_RESERVED_WORDS].filter((keyword) => {\n return !RESERVED_FUNCTIONS.includes(keyword);\n });\n\n const VARIABLE = {\n className: \"variable\",\n begin: /@[a-z0-9]+/,\n };\n\n const OPERATOR = {\n className: \"operator\",\n begin: /[-+*/=%^~]|&&?|\\|\\|?|!=?|<(?:=>?|<|>)?|>[>=]?/,\n relevance: 0,\n };\n\n const FUNCTION_CALL = {\n begin: concat(/\\b/, either(...FUNCTIONS), /\\s*\\(/),\n keywords: {\n built_in: FUNCTIONS\n }\n };\n\n // keywords with less than 3 letters are reduced in relevancy\n function reduceRelevancy(list, {exceptions, when} = {}) {\n const qualifyFn = when;\n exceptions = exceptions || [];\n return list.map((item) => {\n if (item.match(/\\|\\d+$/) || exceptions.includes(item)) {\n return item;\n } else if (qualifyFn(item)) {\n return `${item}|0`;\n } else {\n return item;\n }\n });\n }\n\n return {\n name: 'SQL',\n case_insensitive: true,\n // does not include {} or HTML tags ` x.length < 3 }),\n literal: LITERALS,\n type: TYPES,\n built_in: POSSIBLE_WITHOUT_PARENS\n },\n contains: [\n {\n begin: either(...COMBOS),\n keywords: {\n $pattern: /[\\w\\.]+/,\n keyword: KEYWORDS.concat(COMBOS),\n literal: LITERALS,\n type: TYPES\n },\n },\n {\n className: \"type\",\n begin: either(...MULTI_WORD_TYPES)\n },\n FUNCTION_CALL,\n VARIABLE,\n STRING,\n QUOTED_IDENTIFIER,\n hljs.C_NUMBER_MODE,\n hljs.C_BLOCK_COMMENT_MODE,\n COMMENT_MODE,\n OPERATOR\n ]\n };\n}\n\nmodule.exports = sql;\n","/**\n * @param {string} value\n * @returns {RegExp}\n * */\n\n/**\n * @param {RegExp | string } re\n * @returns {string}\n */\nfunction source(re) {\n if (!re) return null;\n if (typeof re === \"string\") return re;\n\n return re.source;\n}\n\n/**\n * @param {RegExp | string } re\n * @returns {string}\n */\nfunction lookahead(re) {\n return concat('(?=', re, ')');\n}\n\n/**\n * @param {RegExp | string } re\n * @returns {string}\n */\nfunction optional(re) {\n return concat('(', re, ')?');\n}\n\n/**\n * @param {...(RegExp | string) } args\n * @returns {string}\n */\nfunction concat(...args) {\n const joined = args.map((x) => source(x)).join(\"\");\n return joined;\n}\n\n/**\n * Any of the passed expresssions may match\n *\n * Creates a huge this | this | that | that match\n * @param {(RegExp | string)[] } args\n * @returns {string}\n */\nfunction either(...args) {\n const joined = '(' + args.map((x) => source(x)).join(\"|\") + \")\";\n return joined;\n}\n\n/*\nLanguage: HTML, XML\nWebsite: https://www.w3.org/XML/\nCategory: common\nAudit: 2020\n*/\n\n/** @type LanguageFn */\nfunction xml(hljs) {\n // Element names can contain letters, digits, hyphens, underscores, and periods\n const TAG_NAME_RE = concat(/[A-Z_]/, optional(/[A-Z0-9_.-]*:/), /[A-Z0-9_.-]*/);\n const XML_IDENT_RE = /[A-Za-z0-9._:-]+/;\n const XML_ENTITIES = {\n className: 'symbol',\n begin: /&[a-z]+;|&#[0-9]+;|&#x[a-f0-9]+;/\n };\n const XML_META_KEYWORDS = {\n begin: /\\s/,\n contains: [\n {\n className: 'meta-keyword',\n begin: /#?[a-z_][a-z1-9_-]+/,\n illegal: /\\n/\n }\n ]\n };\n const XML_META_PAR_KEYWORDS = hljs.inherit(XML_META_KEYWORDS, {\n begin: /\\(/,\n end: /\\)/\n });\n const APOS_META_STRING_MODE = hljs.inherit(hljs.APOS_STRING_MODE, {\n className: 'meta-string'\n });\n const QUOTE_META_STRING_MODE = hljs.inherit(hljs.QUOTE_STRING_MODE, {\n className: 'meta-string'\n });\n const TAG_INTERNALS = {\n endsWithParent: true,\n illegal: /`]+/\n }\n ]\n }\n ]\n }\n ]\n };\n return {\n name: 'HTML, XML',\n aliases: [\n 'html',\n 'xhtml',\n 'rss',\n 'atom',\n 'xjb',\n 'xsd',\n 'xsl',\n 'plist',\n 'wsf',\n 'svg'\n ],\n case_insensitive: true,\n contains: [\n {\n className: 'meta',\n begin: //,\n relevance: 10,\n contains: [\n XML_META_KEYWORDS,\n QUOTE_META_STRING_MODE,\n APOS_META_STRING_MODE,\n XML_META_PAR_KEYWORDS,\n {\n begin: /\\[/,\n end: /\\]/,\n contains: [\n {\n className: 'meta',\n begin: //,\n contains: [\n XML_META_KEYWORDS,\n XML_META_PAR_KEYWORDS,\n QUOTE_META_STRING_MODE,\n APOS_META_STRING_MODE\n ]\n }\n ]\n }\n ]\n },\n hljs.COMMENT(\n //,\n {\n relevance: 10\n }\n ),\n {\n begin: //,\n relevance: 10\n },\n XML_ENTITIES,\n {\n className: 'meta',\n begin: /<\\?xml/,\n end: /\\?>/,\n relevance: 10\n },\n {\n className: 'tag',\n /*\n The lookahead pattern (?=...) ensures that 'begin' only matches\n ')/,\n end: />/,\n keywords: {\n name: 'style'\n },\n contains: [ TAG_INTERNALS ],\n starts: {\n end: /<\\/style>/,\n returnEnd: true,\n subLanguage: [\n 'css',\n 'xml'\n ]\n }\n },\n {\n className: 'tag',\n // See the comment in the
+
+
+
+
+
+
+
+
+
+
+
+
+
+springdoc-openapi v1.8.0
+
+Table of Contents
+
+- 1. Introduction
+- 2. Getting Started
+- 3. Springdoc-openapi Modules
+
+- 3.1. General overview
+- 3.2. Spring WebMvc support
+- 3.3. Spring WebFlux support
+- 3.4. Spring Hateoas support
+- 3.5. Spring Data Rest support
+- 3.6. Spring Security support
+- 3.7. Actuator support
+- 3.8. Spring Cloud Function Web support
+- 3.9. Kotlin support
+- 3.10. Groovy support
+- 3.11. Javadoc support
+
+
+- 4. Springdoc-openapi Features
+
+- 4.1. Adding API Information and Security documentation
+- 4.2. Error Handling for REST using @ControllerAdvice
+- 4.3. Disabling the
springdoc-openapi endpoints
+- 4.4. Disabling the swagger-ui
+- 4.5. Swagger-ui configuration
+- 4.6. Selecting the Rest Controllers to include in the documentation
+- 4.7. Spring-webflux/WebMvc.fn with Functional Endpoints
+- 4.8. Integration with WildFly
+
+
+- 5. Springdoc-openapi Properties
+
+
+- 6. Springdoc-openapi Plugins
+
+
+- 7. Springdoc-openapi Demos
+
+
+- 8. Migrating from SpringFox
+- 9. Other resources
+
+
+- 10. Sponsor
+
+
+- 11. Special Thanks
+- 12. F.A.Q
+
+- 12.1. How can I define multiple OpenAPI definitions in one Spring Boot project?
+- 12.2. How can I configure Swagger UI?
+- 12.3. How can I filter the resources documented in the output specification by the provided group?
+- 12.4. How can I disable/enable Swagger UI generation based on env variable?
+- 12.5. How can I control the default expansion setting for the operations and tags, in the Swagger UI,
+- 12.6. How can I change the layout of the
swagger-ui?
+- 12.7. How can I sort endpoints alphabetically?
+- 12.8. How can I disable the try it out button?
+- 12.9. How can I add Reusable Enums?
+- 12.10. How can i apply
enumAsRef = true to all enums?
+- 12.11. How can I explicitly set which paths to filter?
+- 12.12. How can I explicitly set which packages to scan?
+- 12.13. How can I set Swagger properties programmatically?
+- 12.14. How can I ignore some field of model?
+- 12.15. How can I ignore
@AuthenticationPrincipal parameter from spring-security?
+- 12.16. Is there a Gradle plugin available?
+- 12.17. How can I hide a parameter from the documentation?
+- 12.18. Is
@Parameters annotation supported?
+- 12.19. Does
springdoc-openapi support Jersey?
+- 12.20. Can
springdoc-openapi generate API only for @RestController?
+- 12.21. Are the following validation annotations supported :
@NotEmpty @NotBlank @PositiveOrZero @NegativeOrZero?
+- 12.22. How can I map
Pageable (spring-data-commons) object to correct URL-Parameter in Swagger UI?
+- 12.23. How can I generate enums in the generated description?
+- 12.24. How can I deploy
springdoc-openapi-ui behind a reverse proxy?
+- 12.25. Is
@JsonView annotations in Spring MVC APIs supported?
+- 12.26. Adding
springdoc-openapi-ui dependency breaks my public/index.html welcome page
+- 12.27. How can I test the Swagger UI?
+- 12.28. How can I customise the OpenAPI object?
+- 12.29. How can I return an empty content as response?
+- 12.30. How are endpoints with multiple consuming media types supported?
+- 12.31. How can I get yaml and json (OpenAPI) in compile time?
+- 12.32. What are the ignored types in the documentation?
+- 12.33. How can i disable ignored types:
+- 12.34. How do I add authorization header in requests?
+- 12.35. Differentiation to Springfox project
+- 12.36. How do I migrate to OpenAPI 3 with springdoc-openapi
+- 12.37. How can I set a global header?
+- 12.38. Are Callbacks supported?
+- 12.39. How can I define SecurityScheme?
+- 12.40. How can I hide an operation or a controller from documentation?
+- 12.41. How to configure global security schemes?
+- 12.42. Can I use spring property with swagger annotations?
+- 12.43. How is server URL generated?
+- 12.44. How can I disable springdoc-openapi cache?
+- 12.45. How can I expose the mvc api-docs endpoints without using the
swagger-ui?
+- 12.46. How can I disable
springdoc-openapi endpoints?
+- 12.47. How can I hide Schema of the the response?
+- 12.48. What is the URL of the
swagger-ui, when I set a different context-path?
+- 12.49. Can I customize OpenAPI object programmatically?
+- 12.50. Where can I find the source code of the demo applications?
+- 12.51. Does this library supports annotations from interfaces?
+- 12.52. What is the list of the excluded parameter types?
+- 12.53. Is file upload supported?
+- 12.54. Can I use
@Parameter inside @Operation annotation?
+- 12.55. Why my parameter is marked as required?
+- 12.56. How are overloaded methods with the same endpoints, but with different parameters
+- 12.57. What is a proper way to set up Swagger UI to use provided spec.yml?
+- 12.58. Is there a way to send authorization header through the @Parameter tag?
+- 12.59. My Rest Controller using @Controller annotation is ignored?
+- 12.60. How can I define groups using application.yml?
+- 12.61. How can I extract fields from parameter object?
+- 12.62. How to Integrate Open API 3 with Spring project (not Spring Boot)?
+- 12.63. How can I use the last
springdoc-openapi SNAPSHOT ?
+- 12.64. How can I use enable
springdoc-openapi MonetaryAmount support?
+- 12.65. How can i aggregate external endpoints (exposing OPENAPI 3 spec) inside one single application?
+- 12.66. How can use custom json/yml file instead of generated one?
+- 12.67. How can i enable CSRF support?
+- 12.68. How can i disable the default swagger petstore URL?
+- 12.69. Is @PageableDefault supported, to enhance the OpenAPI 3 documentation?
+- 12.70. How can I make spring security login-endpoint visible?
+- 12.71. How can I show schema definitions even if the schema is not referenced?
+- 12.72. How to override @Deprecated?
+- 12.73. How can i display a method that returns ModelAndView?
+- 12.74. How can i have pretty-printed output of the OpenApi specification?
+- 12.75. How can i define different schemas for the same class?
+- 12.76. How can i define different description for a class attribute depending on usage?
+- 12.77. Customizing swagger static resources
+- 12.78. What is the compatibility matrix of
springdoc-openapi with spring-boot ?
+- 12.79. Why am i getting an error:
Swagger UI unable to render definition, when overriding the default spring registered HttpMessageConverter?
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+For spring-boot v3 support, make sure you use springdoc-openapi v2
+
+
+
+
+
+springdoc-openapi is on Open Collective. If you ❤️ this project consider becoming a sponsor.
+
+
+This project is sponsored by
+
+
+
+
+
+1. Introduction
+
+
+springdoc-openapi java library helps to automate the generation of API documentation using spring boot projects.
+springdoc-openapi works by examining an application at runtime to infer API semantics based on spring configurations, class structure and various annotations.
+
+
+Automatically generates documentation in JSON/YAML and HTML format APIs.
+This documentation can be completed by comments using swagger-api annotations.
+
+
+This library supports:
+
+
+
+-
+
OpenAPI 3
+
+-
+
Spring-boot (v1, v2 and v3)
+
+-
+
JSR-303, specifically for @NotNull, @Min, @Max, and @Size.
+
+-
+
Swagger-ui
+
+-
+
OAuth 2
+
+-
+
GraalVM native images
+
+
+
+
+The following video introduces the Library:
+
+
+
+
+
+
+
+This is a community-based project, not maintained by the Spring Framework Contributors (Pivotal).
+
+
+
+
+2. Getting Started
+
+
+For the integration between spring-boot and swagger-ui, add the library to the list of your project dependencies (No additional configuration is needed)
+
+
+
+ <dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-ui</artifactId>
+ <version>1.8.0</version>
+ </dependency>
+
+
+
+This will automatically deploy swagger-ui to a spring-boot application:
+
+
+
+-
+
Documentation will be available in HTML format, using the official swagger-ui jars
+
+-
+
The Swagger UI page will then be available at http://server:port/context-path/swagger-ui.html and the OpenAPI description will be available at the following url for json format: http://server:port/context-path/v3/api-docs
+
+
+-
+
server: The server name or IP
+
+-
+
port: The server port
+
+-
+
context-path: The context path of the application
+
+
+
+
+-
+
Documentation will be available in yaml format as well, on the following path : /v3/api-docs.yaml
+
+
+
+
+
+
+
+
+
+
+For custom path of the swagger documentation in HTML format, add a custom springdoc property, in your spring-boot configuration file: .
+
+
+
+
+
+
+# swagger-ui custom path
+springdoc.swagger-ui.path=/swagger-ui.html
+
+
+
+
+
+3. Springdoc-openapi Modules
+
+
+
+3.2. Spring WebMvc support
+
+
+-
+
Documentation will be available at the following url for json format: http://server:port/context-path/v3/api-docs
+
+
+-
+
server: The server name or IP
+
+-
+
port: The server port
+
+-
+
context-path: The context path of the application
+
+
+
+
+-
+
Documentation will be available in yaml format as well, on the following path : /v3/api-docs.yaml
+
+-
+
Add the library to the list of your project dependencies. (No additional configuration is needed)
+
+
+
+
+
+ <dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-webmvc-core</artifactId>
+ <version>1.8.0</version>
+ </dependency>
+
+
+
+
+
+
+
+
+
+This dependency is relevant if you want to generate the OpenAPI description without using the swagger-ui.
+
+
+
+
+
+
+
+
+
+
+
+For custom path of the OpenAPI documentation in Json format, add a custom springdoc property, in your spring-boot configuration file:
+
+
+
+
+
+
+# /api-docs endpoint custom path
+springdoc.api-docs.path=/api-docs
+
+
+
+
+3.3. Spring WebFlux support
+
+
+-
+
Documentation will be available in yaml format as well, on the following path : /v3/api-docs.yaml
+
+-
+
Add the library to the list of your project dependencies (No additional configuration is needed)
+
+
+
+
+
+ <dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-webflux-ui</artifactId>
+ <version>1.8.0</version>
+ </dependency>
+
+
+
+
+3.4. Spring Hateoas support
+
+The support for Spring Hateoas is available using the dependency springdoc-openapi-hateoas.
+The projects that use Spring Hateoas should combine this dependency with the springdoc-openapi-ui dependency.
+This dependency enables the support of Spring Hateoas format.
+
+
+
+ <dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-hateoas</artifactId>
+ <version>1.8.0</version>
+ </dependency>
+
+
+
+
+3.5. Spring Data Rest support
+
+The projects that use spring-data-rest can add the following dependency in combination with the springdoc-openapi-ui dependency.
+This dependency enables the support of spring-boot-starter-data-rest types like: @RepositoryRestResource and QuerydslPredicate annotations.
+
+
+
+ <dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-data-rest</artifactId>
+ <version>1.8.0</version>
+ </dependency>
+
+
+
+
+3.6. Spring Security support
+
+For a project that uses spring-security, you should add the following dependency, in combination with the springdoc-openapi-ui dependency:
+This dependency helps ignoring @AuthenticationPrincipal in case its used on REST Controllers.
+
+
+
+ <dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-security</artifactId>
+ <version>1.8.0</version>
+ </dependency>
+
+
+
+
+3.7. Actuator support
+
+
+-
+
In order to display spring-boot-actuator endpoints, simply add the following property:
+
+
+
+
+
+springdoc.show-actuator=true
+
+
+
+Starting from the release 1.5.1, it will be possible to expose the swagger-ui and the openapi endpoints on actuator port.
+
+
+
+
+
+
+
+
+The actuator management port has to be different from the application port.
+
+
+
+
+
+To expose the swagger-ui, on the management port, you should set
+
+
+
+springdoc.use-management-port=true
+# This property enables the openapi and swagger-ui endpoints to be exposed beneath the actuator base path.
+management.endpoints.web.exposure.include=openapi, swagger-ui
+
+
+
+Once enabled, you should also be able to see the springdoc-openapi endpoints under: (host and port depends on your settings)
+- http://serverName:managementPort/actuator
+
+
+For example, if you have the following settings:
+
+
+Two endpoints will be available:
+
+
+
+-
+
REST API that holdes the OpenAPI definition:
+
+
+-
+
http://serverName:managementPort/actuator/openapi
+
+
+
+
+-
+
An Endpoint, that routes to the swagger-ui:
+
+
+-
+
http://serverName:managementPort/actuator/swagger-ui
+
+
+
+
+
+
+
+
+management.server.port=9090
+
+
+
+For the example, you should also be able to see the springdoc-openapi endpoints:
+
+
+
+-
+
http://serverName:9090/actuator
+
+-
+
http://serverName:9090/actuator/swagger-ui
+
+-
+
http://serverName:9090/actuator/openapi
+
+
+
+
+All the path springdoc-openapi properties are not applicable when springdoc.use-management-port=true.
+
+
+
+
+
+
+
+
+If you want to reach the application endpoints, from the swagger-ui deployed beneath the actuator base path, using a different port from your application, CORS for your endpoints on your application level should be enabled.
+
+
+
+
+
+Additionally, it is also possible to combine this property, with the existing property to display the actuator endpoints in the swagger-ui.
+
+
+
+springdoc.show-actuator=true
+
+
+
+Once enabled:
+- A dedicated group for the actuator endpoints will be by default added.
+- If no group is defined for the application, a default one will be added.
+
+
+The swagger-ui will be then accessible through the actuator port:
+
+
+
+-
+
http://serverName:managementPort/actuator/swagger-ui
+
+
+
+
+If the management port is different from the application port and springdoc.use-management-port is not defined but springdoc.show-actuator is set to true:
+
+
+
+-
+
The swagger-ui will be then accessible through the application port. For example: http://serverName:applicationPort/swagger-ui.html
+
+-
+
A dedicated group for the actuator endpoints will be by default added.
+
+-
+
If no group is defined for the application, a default one will be added.
+
+
+
+
+
+
+
+
+
+
+If you want to reach the actuator endpoints for this case (different port from your application), CORS for your actuator endpoints should be enabled.
+
+
+
+
+
+Note: The naming of these new endpoints beneath the actuator base path cannot be customized for now.
+
+
+
+3.8. Spring Cloud Function Web support
+
+spring-cloud-function-web exposes Java Function as REST endpoint automatically.
+* Since version v1.6.3, the support of functional endpoints has been added.
+
+
+
+-
+
These starters will display the OpenAPI description of the spring-cloud-function-web endpoints.
+
+
+-
+
If you are using spring-web, simply add the springdoc-openapi-ui dependency.
+
+-
+
If you are using spring-webflux, simply add the springdoc-openapi-webflux-ui dependency.
+
+
+
+
+
+
+
+The customisation of the output can be achieved programmatically through OpenApiCustomizer or with the annotations: @RouterOperations and @RouterOperation.
+For annotation usage, you have:
+* @RouterOperation: It can be used alone, if the customisation is related to a single REST API.
+When using @RouterOperation, it’s not mandatory to fill the path
+
+
+
+-
+
@RouterOperation, contains the @Operation annotation.
+The @Operation annotation can also be placed on the bean method level if the property beanMethod is declared.
+
+
+
+
+
+
+
+
+
+
+Don’t forget to set operationId which is mandatory.
+
+
+
+
+
+
+@Bean
+@RouterOperation(operation = @Operation(description = "Say hello", operationId = "hello", tags = "persons",
+ responses = @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = PersonDTO.class)))))
+public Supplier<PersonDTO> helloSupplier() {
+ return () -> new PersonDTO();
+}
+
+
+
+
+
+-
+
@RouterOperations: This annotation should be used to describe the multiple REST APIs exposed by spring-cloud-function-web.
+When using RouterOperations, it’s mandatory to fill the method property.
+
+-
+
A @RouterOperations, contains many @RouterOperation.
+
+
+
+
+
+@Bean
+@RouterOperations({
+ @RouterOperation(method = RequestMethod.GET, operation = @Operation(description = "Say hello GET", operationId = "lowercaseGET", tags = "persons")),
+ @RouterOperation(method = RequestMethod.POST, operation = @Operation(description = "Say hello POST", operationId = "lowercasePOST", tags = "positions"))
+})
+public Function<Flux<String>, Flux<String>> lowercase() {
+ return flux -> flux.map(value -> value.toLowerCase());
+}
+
+
+
+
+Some code samples are available on GITHUB of demos:
+
+
+
+
+3.9. Kotlin support
+
+For a project that uses Kotlin, you should add the following dependency.
+This dependency improves the support of Kotlin types:
+
+
+
+ <dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-kotlin</artifactId>
+ <version>1.8.0</version>
+ </dependency>
+
+
+
+
+-
+
If you are using spring-web, you should combine the springdoc-openapi-kotlin module with springdoc-openapi-ui.
+
+-
+
If you are using spring-webflux, you should combine the springdoc-openapi-kotlin module with springdoc-openapi-webflux-ui.
+
+
+
+
+
+3.10. Groovy support
+
+For a project that uses Groovy, you should add the following dependency, in combination with the springdoc-openapi-ui dependency:
+This dependency improves the support of Kotlin types:
+
+
+
+ <dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-groovy</artifactId>
+ <version>1.8.0</version>
+ </dependency>
+
+
+
+
+3.11. Javadoc support
+
+For a project that wants to enable javadoc support, you should add the following dependency, in combination with the springdoc-openapi-ui dependency:
+
+
+
+ <dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-javadoc</artifactId>
+ <version>1.8.0</version>
+ </dependency>
+
+
+
+This dependency improves the support of javadoc tags and comments:
+
+
+
+-
+
The javadoc comment of a method: is resolved as the @Operation description
+
+-
+
@return : is resolved as the @Operation response description
+
+-
+
The javadoc comment of an attribute: is resolved as '@Schema' description for this field.
+
+
+
+
+This dependency is based on the library therapi-runtime-javadoc
+
+
+
+
+
+
+
+
+Make sure, you enable the annotation processor of therapi-runtime-javadoc in order to enable javadoc support for springdoc-openapi.
+
+
+
+
+
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <annotationProcessorPaths>
+ <path>
+ <groupId>com.github.therapi</groupId>
+ <artifactId>therapi-runtime-javadoc-scribe</artifactId>
+ <version>0.15.0</version>
+ </path>
+ </annotationProcessorPaths>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+
+
+
+
+
+
+
+
+If both a swagger-annotation description and a javadoc comment are present. The value of the swagger-annotation description will be used.
+
+
+
+
+
+
+
+
+4. Springdoc-openapi Features
+
+
+4.1. Adding API Information and Security documentation
+
+The library uses spring-boot application auto-configured packages to scan for the following annotations in spring beans: OpenAPIDefinition and Info.
+These annotations declare, API Information: Title, version, licence, security, servers, tags, security and externalDocs.
+For better performance of documentation generation, declare @OpenAPIDefinition and @SecurityScheme annotations within a spring managed bean.
+
+
+
+4.2. Error Handling for REST using @ControllerAdvice
+
+To generate documentation automatically, make sure all the methods declare the HTTP Code responses using the annotation: @ResponseStatus
+
+
+
+4.3. Disabling the springdoc-openapi endpoints
+
+In order to disable the springdoc-openapi endpoint (/v3/api-docs by default) use the following property:
+
+
+
+# Disabling the /v3/api-docs endpoint
+springdoc.api-docs.enabled=false
+
+
+
+
+4.4. Disabling the swagger-ui
+
+In order to disable the swagger-ui, use the following property:
+
+
+
+# Disabling the swagger-ui
+springdoc.swagger-ui.enabled=false
+
+
+
+
+4.5. Swagger-ui configuration
+
+The library supports the swagger-ui official properties:
+
+
+
+You need to declare swagger-ui properties as spring-boot properties.
+All these properties should be declared with the following prefix: springdoc.swagger-ui
+
+
+
+4.6. Selecting the Rest Controllers to include in the documentation
+
+Additionally, to @Hidden annotation from swagger-annotations, its possible to restrict the generated OpenAPI description using package or path configuration.
+
+
+For the list of packages to include, use the following property:
+
+
+
+# Packages to include
+springdoc.packagesToScan=com.package1, com.package2
+
+
+
+For the list of paths to include, use the following property:
+
+
+
+# Paths to include
+springdoc.pathsToMatch=/v1, /api/balance/**
+
+
+
+
+4.7. Spring-webflux/WebMvc.fn with Functional Endpoints
+
+Since version v1.5.0, a functional DSL has been introduced, thanks to this enhancement in the spring-framework: #25938
+
+
+It’s an alternative functional API to the @RouterOperations annotations.
+
+
+This is a sample DSL, to generate OpenAPI description to the webflux/WebMvc.fn REST endpoints:
+
+
+
+@Bean
+RouterFunction<?> routes() {
+ return route().GET("/foo", HANDLER_FUNCTION, ops -> ops
+ .operationId("hello")
+ .parameter(parameterBuilder().name("key1").description("My key1 description"))
+ .parameter(parameterBuilder().name("key2").description("My key2 description"))
+ .response(responseBuilder().responseCode("200").description("This is normal response description"))
+ .response(responseBuilder().responseCode("404").description("This is another response description"))
+ ).build();
+}
+
+
+
+
+Here is the link for some sample codes:
+
+
+
+-
+
+
+-
+
+
+-
+
+
+-
+
+
+-
+
+
+
+
+
+And the Demo code, using the functional endpoints DSL:
+
+
+
+Since version v1.3.8, the support of functional endpoints has been added.
+Two main annotations have been added for this purpose: @RouterOperations and @RouterOperation.
+
+
+Only REST APIs with the @RouterOperations and @RouterOperation can be displayed on the swagger-ui.
+
+
+
+-
+
@RouterOperation: It can be used alone, if the Router bean contains one single route related to the REST API..
+When using @RouterOperation, its not mandatory to fill the path
+
+-
+
@RouterOperation, can reference directly a spring Bean (beanClass property) and the underlying method (beanMethod property): Springdoc-openapi, will then inspect this method and the swagger annotations on this method level.
+
+
+
+
+
+@Bean
+@RouterOperation(beanClass = EmployeeService.class, beanMethod = "findAllEmployees")
+RouterFunction<ServerResponse> getAllEmployeesRoute() {
+ return route(GET("/employees").and(accept(MediaType.APPLICATION_JSON)),
+ req -> ok().body(
+ employeeService().findAllEmployees(), Employee.class));
+}
+
+
+
+
+
+-
+
@RouterOperation, contains the @Operation annotation.
+The @Operation annotation can also be placed on the bean method level if the property beanMethod is declared.
+
+
+
+
+
+
+
+
+
+
+Don’t forget to set operationId which is mandatory.
+
+
+
+
+
+
+@Bean
+@RouterOperation(operation = @Operation(operationId = "findEmployeeById", summary = "Find purchase order by ID", tags = { "MyEmployee" },
+ parameters = { @Parameter(in = ParameterIn.PATH, name = "id", description = "Employee Id") },
+ responses = { @ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(implementation = Employee.class))),
+ @ApiResponse(responseCode = "400", description = "Invalid Employee ID supplied"),
+ @ApiResponse(responseCode = "404", description = "Employee not found") }))
+RouterFunction<ServerResponse> getEmployeeByIdRoute() {
+ return route(GET("/employees/{id}"),
+ req -> ok().body(
+ employeeRepository().findEmployeeById(req.pathVariable("id")), Employee.class));
+}
+
+
+
+
+
+-
+
@RouterOperations: This annotation should be used if the Router bean contains multiple routes.
+When using RouterOperations, its mandatory to fill the path property.
+
+-
+
A @RouterOperations, contains many @RouterOperation.
+
+
+
+
+
+@RouterOperations({ @RouterOperation(path = "/getAllPersons", beanClass = PersonService.class, beanMethod = "getAll"),
+ @RouterOperation(path = "/getPerson/{id}", beanClass = PersonService.class, beanMethod = "getById"),
+ @RouterOperation(path = "/createPerson", beanClass = PersonService.class, beanMethod = "save"),
+ @RouterOperation(path = "/deletePerson/{id}", beanClass = PersonService.class, beanMethod = "delete") })
+@Bean
+public RouterFunction<ServerResponse> personRoute(PersonHandler handler) {
+ return RouterFunctions
+ .route(GET("/getAllPersons").and(accept(MediaType.APPLICATION_JSON)), handler::findAll)
+ .andRoute(GET("/getPerson/{id}").and(accept(MediaType.APPLICATION_STREAM_JSON)), handler::findById)
+ .andRoute(POST("/createPerson").and(accept(MediaType.APPLICATION_JSON)), handler::save)
+ .andRoute(DELETE("/deletePerson/{id}").and(accept(MediaType.APPLICATION_JSON)), handler::delete);
+}
+
+
+
+
+All the documentations filled using @RouterOperation, might be completed by the router function data.
+For that, @RouterOperation fields must help identify uniquely the concerned route.
+springdoc-openpi scans for a unique route related to a @RouterOperation annotation, using on the following criteria:
+
+
+
+-
+
by path
+
+-
+
by path and RequestMethod
+
+-
+
by path and produces
+
+-
+
by path and consumes
+
+-
+
by path and RequestMethod and produces
+
+-
+
by path and RequestMethod and consumes
+
+-
+
by path and produces and consumes
+
+-
+
by path and RequestMethod and produces and consumes
+
+
+
+
+Some code samples are available on GITHUB of demos:
+
+
+
+And some project tests: (from app69 to app75)
+
+
+
+
+
+
+
+5. Springdoc-openapi Properties
+
+
+springdoc-openapi relies on standard spring configuration properties (yml or properties) using the standard files locations.
+
+
+5.1. springdoc-openapi core properties
+
+
+
+
+
+Parameter name
+Default Value
+Description
+
+
+
+
+springdoc.api-docs.path
/v3/api-docs
String, For custom path of the OpenAPI documentation in Json format.
+
+springdoc.api-docs.enabled
true
Boolean. To disable the springdoc-openapi endpoint (/v3/api-docs by default).
+
+springdoc.packages-to-scan
*
List of Strings.The list of packages to scan (comma separated)
+
+springdoc.paths-to-match
/*
List of Strings.The list of paths to match (comma separated)
+
+springdoc.produces-to-match
/*
List of Strings.The list of produces mediaTypes to match (comma separated)
+
+springdoc.headers-to-match
/*
List of Strings.The list of headers to match (comma separated)
+
+springdoc.consumes-to-match
/*
List of Strings.The list of consumes mediaTypes to match (comma separated)
+
+springdoc.paths-to-exclude
List of Strings.The list of paths to exclude (comma separated)
+
+springdoc.packages-to-exclude
List of Strings.The list of packages to exclude (comma separated)
+
+springdoc.default-consumes-media-type
application/json
String. The default consumes media type.
+
+springdoc.default-produces-media-type
/
String.The default produces media type.
+
+springdoc.cache.disabled
false
Boolean. To disable the springdoc-openapi cache of the calculated OpenAPI.
+
+springdoc.show-actuator
false
Boolean. To display the actuator endpoints.
+
+springdoc.auto-tag-classes
true
Boolean. To disable the springdoc-openapi automatic tags.
+
+springdoc.model-and-view-allowed
false
Boolean. To allow RestControllers with ModelAndView return to appear in the OpenAPI description.
+
+springdoc.override-with-generic-response
true
Boolean. When true, automatically adds @ControllerAdvice responses to all the generated responses.
+
+springdoc.group-configs[0].group
String.The group name
+
+springdoc.group-configs[0].display-name
String.The display name of the group.
+
+springdoc.group-configs[0].packages-to-scan
*
List of Strings.The list of packages to scan for a group (comma separated)
+
+springdoc.group-configs[0].paths-to-match
/*
List of Strings.The list of paths to match for a group(comma separated)
+
+springdoc.group-configs[0].paths-to-exclude
``
List of Strings.The list of paths to exclude for a group(comma separated)
+
+springdoc.group-configs[0].packages-to-exclude
List of Strings.The list of packages to exclude for a group(comma separated)
+
+springdoc.group-configs[0].produces-to-match
/*
List of Strings.The list of produces mediaTypes to match (comma separated)
+
+springdoc.group-configs[0].consumes-to-match
/*
List of Strings.The list of consumes mediaTypes to match (comma separated)
+
+springdoc.group-configs[0].headers-to-match
/*
List of Strings.The list of headers to match (comma separated)
+
+springdoc.webjars.prefix
/webjars
String, To change the webjars prefix that is visible the URL of swagger-ui for spring-webflux.
+
+springdoc.api-docs.resolve-schema-properties
false
Boolean. To enable property resolver on @Schema (name, title and description).
+
+springdoc.remove-broken-reference-definitions
true
Boolean. To disable removal of broken reference definitions.
+
+springdoc.writer-with-default-pretty-printer
false
Boolean. To enable pretty print of the OpenApi specification.
+
+springdoc.model-converters.deprecating-converter.enabled
true
Boolean. To disable deprecating model converter.
+
+springdoc.model-converters.polymorphic-converter.enabled
true
Boolean. To disable polymorphic model converter.
+
+springdoc.model-converters.pageable-converter.enabled
true
Boolean. To disable pageable model converter.
+
+springdoc.model-converters.sort-converter.enabled
true
Boolean. To disable Sort converter.
+
+springdoc.use-fqn
false
Boolean. To enable fully qualified names.
+
+springdoc.show-login-endpoint
false
Boolean. To make spring security login-endpoint visible.
+
+springdoc.pre-loading-enabled
false
Boolean. Pre-loading setting to load OpenAPI on application startup.
+
+springdoc.pre-loading-locales
List of Strings.The list of locales to load OpenAPI on application startup.(comma separated) If not specified, it will preload with the default Locale.
+
+springdoc.writer-with-order-by-keys
false
Boolean. Enable a deterministic/alphabetical ordering.
+
+springdoc.use-management-port
false
Boolean. To expose the swagger-ui on the actuator management port.
+
+springdoc.disable-i18n
false
Boolean. To disable automatic translation using i18n.
+
+springdoc.show-spring-cloud-functions
true
Boolean. To display the spring-cloud-function web endpoints.
+
+springdoc.api-docs.version
openapi_3_0
String. To Choose OpenAPI 3.0 or OpenAPI 3.1 (using the value OPENAPI_3_1).
+
+springdoc.default-flat-param-object
false
Boolean. To default flatten parameter.
+
+springdoc.default-support-form-data
false
Boolean. To default set parameters to form data when specifying api to accept form data.
+
+springdoc.nullable-request-parameter-enabled
true
Boolean. To default Enable Support for nullable request parameters in Kotlin.
+
+springdoc.show-oauth2-endpoints
false
Boolean. To make spring security oauth2-endpoint visible.
+
+springdoc.api-docs.resolve-extensions-properties
false
Boolean. To enable support of spring property resolver for @ExtensionProperty.
+
+springdoc.enable-default-api-docs
true
Boolean. To enable default OpenAPI endpoint /v3/api-docs.
+
+springdoc.trim-kotlin-indent
false
Boolean. Adjust indentation when parsing the @Operation annotation in Kotlin.
+
+
+
+
+5.2. swagger-ui properties
+
+
+-
+
The support of the swagger-ui properties is available on springdoc-openapi. See Official documentation.
+
+-
+
You can use the same swagger-ui properties in the documentation as Spring Boot properties.
+
+
+
+
+
+
+
+
+
+
+All these properties should be declared with the following prefix: springdoc.swagger-ui
+
+
+
+
+
+
+
+
+
+Parameter name
+Default Value
+Description
+
+
+
+
+springdoc.swagger-ui.path
/swagger-ui.html
String, For custom path of the swagger-ui HTML documentation.
+
+springdoc.swagger-ui.enabled
true
Boolean. To disable the swagger-ui endpoint (/swagger-ui.html by default).
+
+springdoc.swagger-ui.configUrl
/v3/api-docs/swagger-config
String. URL to fetch external configuration document from.
+
+springdoc.swagger-ui.layout
BaseLayout
String. The name of a component available via the plugin system to use as the top-level layout for Swagger UI.
+
+springdoc.swagger-ui.validatorUrl
By default, Swagger UI does not validate specs. You can use this parameter to set a validator URL, for example for against swagger.io’s online validator.
+
+springdoc.swagger-ui.tryItOutEnabled
true
Boolean. Controls whether the "Try it out" section should be enabled by default.
+
+springdoc.swagger-ui.filter
false
Boolean OR String. If set, enables filtering. The top bar will show an edit box that you can use to filter the tagged operations that are shown. Can be Boolean to enable or disable, or a string, in which case filtering will be enabled using that string as the filter expression. Filtering is case sensitive matching the filter expression anywhere inside the tag.
+
+springdoc.swagger-ui.operationsSorter
Function=(a ⇒ a). Apply a sort to the operation list of each API. It can be 'alpha' (sort by paths alphanumerically), 'method' (sort by HTTP method) or a function (see Array.prototype.sort() to know how sort function works). Default is the order returned by the server unchanged.
+
+springdoc.swagger-ui.tagsSorter
Function=(a ⇒ a). Apply a sort to the tag list of each API. It can be 'alpha' (sort by paths alphanumerically) or a function see Array.prototype.sort() to learn how to write a sort function). Two tag name strings are passed to the sorter for each pass. Default is the order determined by Swagger UI.
+
+springdoc.swagger-ui.oauth2RedirectUrl
/swagger-ui/oauth2-redirect.html
String. OAuth redirect URL.
+
+springdoc.swagger-ui.displayOperationId
false
Boolean. Controls the display of operationId in operations list. The default is false.
+
+springdoc.swagger-ui.displayRequestDuration
false
Boolean. Controls the display of the request duration (in milliseconds) for "Try it out" requests.
+
+springdoc.swagger-ui.deepLinking
false
Boolean. If set to true, enables deep linking for tags and operations. See the [Deep Linking documentation](swagger.io/docs/open-source-tools/swagger-ui/usage/deep-linking) for more information.
+
+springdoc.swagger-ui.defaultModelsExpandDepth
1
Number. The default expansion depth for models (set to -1 completely hide the models).
+
+springdoc.swagger-ui.defaultModelExpandDepth
1
Number. The default expansion depth for the model on the model-example section.
+
+springdoc.swagger-ui.defaultModelRendering
String=["example"*, "model"]. Controls how the model is shown when the API is first rendered. (The user can always switch the rendering for a given model by clicking the 'Model' and 'Example Value' links.)
+
+springdoc.swagger-ui.docExpansion
String=["list"*, "full", "none"]. Controls the default expansion setting for the operations and tags. It can be 'list' (expands only the tags), 'full' (expands the tags and operations) or 'none' (expands nothing).
+
+springdoc.swagger-ui.maxDisplayedTags
Number. If set, limits the number of tagged operations displayed to at most this many. The default is to show all operations.
+
+springdoc.swagger-ui.showExtensions
false
Boolean. Controls the display of vendor extension (x-) fields and values for Operations, Parameters, and Schema.
+
+springdoc.swagger-ui.url
String.To configure, the path of a custom OpenAPI file . Will be ignored if urls is used.
+
+springdoc.swagger-ui.showCommonExtensions
false
Boolean. Controls the display of extensions (pattern, maxLength, minLength, maximum, minimum) fields and values for Parameters.
+
+springdoc.swagger-ui.supportedSubmitMethods
Array=[get, put, post, delete, options, head, patch, trace]. List of HTTP methods that have the "Try it out" feature enabled. An empty array disables "Try it out" for all operations. This does not filter the operations from the display.
+
+springdoc.swagger-ui.queryConfigEnabled
false
Boolean. Disabled since v1.6.0. This parameter enables (legacy) overriding configuration parameters via URL search params. See security advisory before enabling this feature.
+
+springdoc.swagger-ui.oauth. additionalQueryStringParams
String. Additional query parameters added to authorizationUrl and tokenUrl.
+
+springdoc.swagger-ui.disable-swagger-default-url
false
Boolean. To disable the swagger-ui default petstore url. (Available since v1.4.1).
+
+springdoc.swagger-ui.urls[0].url
URL. The url of the swagger group, used by Topbar plugin. URLs must be unique among all items in this array, since they’re used as identifiers.
+
+springdoc.swagger-ui.urls[0].name
String. The name of the swagger group, used by Topbar plugin. Names must be unique among all items in this array, since they’re used as identifiers.
+
+springdoc.swagger-ui.urlsPrimaryName
String. The name of the swagger group which will be displayed when Swagger UI loads.
+
+springdoc.swagger-ui.oauth.clientId
String. Default clientId. MUST be a string.
+
+springdoc.swagger-ui.oauth.clientSecret
String. Default clientSecret. Never use this parameter in your production environment. It exposes crucial security information. This feature is intended for dev/test environments only.
+
+springdoc.swagger-ui.oauth.realm
String. realm query parameter (for OAuth 1) added to authorizationUrl and tokenUrl.
+
+springdoc.swagger-ui.oauth.appName
String. OAuth application name, displayed in authorization popup.
+
+springdoc.swagger-ui.oauth.scopeSeparator
String. OAuth scope separator for passing scopes, encoded before calling, default value is a space (encoded value %20).
+
+springdoc.swagger-ui.csrf.enabled
false
Boolean. To enable CSRF support
+
+springdoc.swagger-ui.csrf.use-local-storage
false
Boolean. To get the CSRF token from the Local Storage.
+
+springdoc.swagger-ui.csrf.use-session-storage
false
Boolean. To get the CSRF token from the Session Storage.
+
+springdoc.swagger-ui.csrf.cookie-name
XSRF-TOKEN
String. Optional CSRF, to set the CSRF cookie name.
+
+springdoc.swagger-ui.csrf.header-name
X-XSRF-TOKEN
String. Optional CSRF, to set the CSRF header name.
+
+springdoc.swagger-ui.syntaxHighlight.activated
true
Boolean. Whether syntax highlighting should be activated or not.
+
+springdoc.swagger-ui.syntaxHighlight.theme
agate
String. String=["agate"*, "arta", "monokai", "nord", "obsidian", "tomorrow-night"]. Highlight.js syntax coloring theme to use. (Only these 6 styles are available.)
+
+springdoc.swagger-ui.oauth. useBasicAuthentication WithAccessCodeGrant
false
Boolean. Only activated for the accessCode flow. During the authorization_code request to the tokenUrl, pass the Client Password using the HTTP Basic Authentication scheme (Authorization header with Basic base64encode(client_id + client_secret)).
+
+springdoc.swagger-ui.oauth. usePkceWithAuthorization CodeGrant
false
Boolean.Only applies to authorizatonCode flows. Proof Key for Code Exchange brings enhanced security for OAuth public clients.
+
+springdoc.swagger-ui.persistAuthorization
false
Boolean. If set to true, it persists authorization data and it would not be lost on browser close/refresh
+
+springdoc.swagger-ui.use-root-path
false
Boolean. If set to true, the swagger-ui will be accessible from the application root path directly.
+
+
+
+
+
+
+6. Springdoc-openapi Plugins
+
+
+6.1. Maven plugin
+
+The aim of springdoc-openapi-maven-plugin is to generate json and yaml OpenAPI description during build time.
+The plugin works during integration-tests phase, and generate the OpenAPI description.
+The plugin works in conjunction with spring-boot-maven plugin.
+
+
+You can test it during the integration tests phase using the maven command:
+
+
+
+mvn verify
+
+
+
+In order to use this functionality, you need to add the plugin declaration on the plugins section of your pom.xml:
+
+
+
+<plugin>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-maven-plugin</artifactId>
+ <version>${spring-boot-maven-plugin.version}</version>
+ <configuration>
+ <jvmArguments>-Dspring.application.admin.enabled=true</jvmArguments>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>start</goal>
+ <goal>stop</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
+<plugin>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-maven-plugin</artifactId>
+ <version>1.5</version>
+ <executions>
+ <execution>
+ <id>integration-test</id>
+ <goals>
+ <goal>generate</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
+
+
+
+For more custom settings of the springdoc-openapi-maven-plugin, you can consult the plugin documentation:
+
+
+
+
+6.2. Gradle plugin
+
+This plugin allows you to generate an OpenAPI 3 specification for a Spring Boot application from a Gradle build.
+
+
+
+plugins {
+ id("org.springframework.boot") version "2.7.0"
+ id("org.springdoc.openapi-gradle-plugin") version "1.9.0"
+}
+
+
+
+
+When you add this plugin and its runtime dependency plugins to your build file, the plugin creates the following tasks:
+
+
+
+-
+
forkedSpringBootRun
+
+-
+
generateOpenApiDocs
+
+
+
+
+
+gradle clean generateOpenApiDocs
+
+
+
+For more custom configuration of springdoc-openapi-gradle-plugin ,you can consult the plugin documentation:
+
+
+
+
+
+
+7. Springdoc-openapi Demos
+
+
+7.1. springdoc applications demos
+
+
+-
+
+
+-
+
+
+-
+
+
+-
+
Demo Spring Boot 2 WebFlux with Functional endpoints OpenAPI 3
+
+-
+
+
+-
+
+
+-
+
+
+-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+8. Migrating from SpringFox
+
+
+
+-
+
Remove springfox and swagger 2 dependencies. Add springdoc-openapi-ui dependency instead.
+
+
+
+
+
+ <dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-ui</artifactId>
+ <version>1.8.0</version>
+ </dependency>
+
+
+
+
+-
+
Replace swagger 2 annotations with swagger 3 annotations (it is already included with springdoc-openapi-ui dependency).
+Package for swagger 3 annotations is io.swagger.v3.oas.annotations.
+
+
+-
+
@Api → @Tag
+
+-
+
@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
+
+-
+
@ApiImplicitParam → @Parameter
+
+-
+
@ApiImplicitParams → @Parameters
+
+-
+
@ApiModel → @Schema
+
+-
+
@ApiModelProperty(allowEmptyValue = true) → @Schema(nullable = true)
+
+-
+
@ApiModelProperty → @Schema
+
+-
+
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
+
+-
+
@ApiParam → @Parameter
+
+-
+
@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")
+
+
+
+
+-
+
If you’re using an object to capture multiple request query params, annotation that method argument with @ParameterObject
+
+-
+
This step is optional: Only if you have multiple Docket beans replace them with GroupedOpenApi beans.
+
+
+
+
+Before:
+
+
+
+ @Bean
+ public Docket publicApi() {
+ return new Docket(DocumentationType.SWAGGER_2)
+ .select()
+ .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public"))
+ .paths(PathSelectors.regex("/public.*"))
+ .build()
+ .groupName("springshop-public")
+ .apiInfo(apiInfo());
+ }
+
+ @Bean
+ public Docket adminApi() {
+ return new Docket(DocumentationType.SWAGGER_2)
+ .select()
+ .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.admin"))
+ .paths(PathSelectors.regex("/admin.*"))
+ .apis(RequestHandlerSelectors.withMethodAnnotation(Admin.class))
+ .build()
+ .groupName("springshop-admin")
+ .apiInfo(apiInfo());
+ }
+
+
+
+
+Now:
+
+
+
+ @Bean
+ public GroupedOpenApi publicApi() {
+ return GroupedOpenApi.builder()
+ .group("springshop-public")
+ .pathsToMatch("/public/**")
+ .build();
+ }
+ @Bean
+ public GroupedOpenApi adminApi() {
+ return GroupedOpenApi.builder()
+ .group("springshop-admin")
+ .pathsToMatch("/admin/**")
+ .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class))
+ .build();
+ }
+
+
+
+
+If you have only one Docket — remove it and instead add properties to your application.properties:
+
+
+
+springdoc.packagesToScan=package1, package2
+springdoc.pathsToMatch=/v1, /api/balance/**
+
+
+
+
+-
+
Add bean of OpenAPI type. See example:
+
+
+
+
+
+ @Bean
+ public OpenAPI springShopOpenAPI() {
+ return new OpenAPI()
+ .info(new Info().title("SpringShop API")
+ .description("Spring shop sample application")
+ .version("v0.0.1")
+ .license(new License().name("Apache 2.0").url("http://springdoc.org")))
+ .externalDocs(new ExternalDocumentation()
+ .description("SpringShop Wiki Documentation")
+ .url("https://springshop.wiki.github.org/docs"));
+ }
+
+
+
+
+
+-
+
If the swagger-ui is served behind a proxy:
+
+
+-
+
To customise the Swagger UI
+
+
+
+
+-
+
To hide an operation or a controller from documentation
+
+
+
+
+
+
+
+9. Other resources
+
+
+
+
+
+
+10. Sponsor
+
+
+springdoc-openapi is on Open Collective.
+
+
+If you ❤️ this project consider becoming a sponsor.
+
+
+This money is used to cover project expenses and your donation will help the project live and grow successfully.
+
+
+Thank you to our bronze sponsors!
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+10.1. Benefits of being a bronze sponsor
+
+Bronze sponsors donate $50 per month to the project, and get the following benefits:
+
+
+
+-
+
You will receive a Sponsor badge 🎖!. Visibility on the front page of springdoc.org in the welcome page (about 55,000 views/month on May, 2022).
+
+-
+
“Thank you” tweet from `springdoc team'.
+
+
+
+
+
+10.2. Benefits of being a silver sponsor
+
+Silver sponsors donate $100 per month to the project, and get the following benefits:
+
+
+
+-
+
Same benefits as bronze sponsors (visibility on main pages, and thank you tweet).
+
+-
+
The ability to get support for 2 issues every month, non transferable.
+
+-
+
If issues are not created by the end of the month, it is lost
+
+
+
+
+
+10.3. Benefits of being a gold sponsor
+
+Gold sponsors donate $500 per month to the project, and get the following benefits:
+
+
+
+-
+
Same benefits as silver sponsors (visibility on main pages, and thank you tweet).
+
+-
+
The ability to get support for 10 issues every month, non transferable.
+
+-
+
Company logos on all springdoc.org page footers
+
+-
+
If issues are not created by the end of the month, the remaining ones are lost.
+
+
+
+
+
+
+
+11. Special Thanks
+
+
+
+-
+
Thank you to The Spring Team for sharing all relevant resources around Spring projects.
+
+-
+
Thanks a lot JetBrains for supporting springdoc-openapi project.
+
+
+
+
+
+
+
+
+
+
+
+12. F.A.Q
+
+
+12.1. How can I define multiple OpenAPI definitions in one Spring Boot project?
+
+You can define your own groups of API based on the combination of: API paths and packages to scan. Each group should have a unique groupName.
+The OpenAPI description of this group, will be available by default on:
+
+
+
+-
+
http://server:port/context-path/v3/api-docs/groupName
+
+
+
+
+To enable the support of multiple OpenAPI definitions, a bean of type GroupedOpenApi needs to be defined.
+
+
+For the following Group definition(based on package path), the OpenAPI description URL will be : /v3/api-docs/stores
+
+
+
+@Bean
+public GroupedOpenApi storeOpenApi() {
+ String paths[] = {"/store/**"};
+ return GroupedOpenApi.builder().group("stores").pathsToMatch(paths)
+ .build();
+}
+
+
+
+
+For the following Group definition (based on package name), the OpenAPI description URL will be: /v3/api-docs/users
+
+
+
+@Bean
+public GroupedOpenApi userOpenApi() {
+ String packagesToscan[] = {"test.org.springdoc.api.app68.api.user"};
+ return GroupedOpenApi.builder().group("users").packagesToScan(packagesToscan)
+ .build();
+}
+
+
+
+
+For the following Group definition(based on path), the OpenAPI description URL will be: /v3/api-docs/pets
+
+
+
+@Bean
+public GroupedOpenApi petOpenApi() {
+ String paths[] = {"/pet/**"};
+ return GroupedOpenApi.builder().group("pets").pathsToMatch(paths)
+ .build();
+}
+
+
+
+
+For the following Group definition (based on package name and path), the OpenAPI description URL will be: /v3/api-docs/groups
+
+
+
+@Bean
+public GroupedOpenApi groupOpenApi() {
+ String paths[] = {"/v1/**"};
+ String packagesToscan[] = {"test.org.springdoc.api.app68.api.user", "test.org.springdoc.api.app68.api.store"};
+ return GroupedOpenApi.builder().group("groups").pathsToMatch(paths).packagesToScan(packagesToscan)
+ .build();
+}
+
+
+
+
+For more details about the usage, you can have a look at the following sample Test:
+
+
+
+
+12.2. How can I configure Swagger UI?
+
+
+-
+
The support of the swagger official properties is available on springdoc-openapi. See Official documentation.
+
+-
+
You can use the same swagger properties in the documentation as Spring Boot properties.
+
+
+
+
+
+
+
+
+
+
+All these properties should be declared with the following prefix: springdoc.swagger-ui
+
+
+
+
+
+
+12.3. How can I filter the resources documented in the output specification by the provided group?
+
+
+-
+
You can use the standard swagger-ui property filter.
+
+
+
+
+
+springdoc.swagger-ui.filter=group-a
+
+
+
+
+12.4. How can I disable/enable Swagger UI generation based on env variable?
+
+
+-
+
This property helps you disable only the UI.
+
+
+
+
+
+springdoc.swagger-ui.enabled=false
+
+
+
+
+12.5. How can I control the default expansion setting for the operations and tags, in the Swagger UI,
+
+
+-
+
You can set this property in your application.yml like so for example:
+
+
+
+
+
+springdoc.swagger-ui.doc-expansion= none
+
+
+
+
+12.6. How can I change the layout of the swagger-ui?
+
+
+-
+
For layout options, you can use swagger-ui configuration options. For example:
+
+
+
+
+
+springdoc.swagger-ui.layout=BaseLayout
+
+
+
+
+12.7. How can I sort endpoints alphabetically?
+
+
+-
+
You can use the following springdoc-openapi properties:
+
+
+
+
+
+#For sorting endpoints alphabetically
+springdoc.swagger-ui.operationsSorter=alpha
+#For sorting tags alphabetically
+springdoc.swagger-ui.tagsSorter=alpha
+
+
+
+
+12.8. How can I disable the try it out button?
+
+
+-
+
You have to set the following property:
+
+
+
+
+
+springdoc.swagger-ui.supportedSubmitMethods=get, put, post, delete, options, head, patch, trace
+
+
+
+
+12.9. How can I add Reusable Enums?
+
+
+-
+
You should add @Schema(enumAsRef = true) on your enum.
+
+
+
+
+
+12.10. How can i apply enumAsRef = true to all enums?
+
+
+-
+
Declare the following property:
+
+
+
+
+
+static {
+ io.swagger.v3.core.jackson.ModelResolver.enumsAsRef = true;
+}
+
+
+
+
+12.11. How can I explicitly set which paths to filter?
+
+
+-
+
You can set list of paths to include using the following property:
+
+
+
+
+
+springdoc.pathsToMatch=/v1, /api/balance/**
+
+
+
+
+12.12. How can I explicitly set which packages to scan?
+
+
+-
+
You can set list of packages to include using the following property:
+
+
+
+
+
+springdoc.packagesToScan=package1, package2
+
+
+
+
+12.13. How can I set Swagger properties programmatically?
+
+These can be set by creating a swaggerUiConfig bean as follows:
+
+
+
+@Bean
+@Primary
+fun swaggerUiConfig(config: SwaggerUiConfigProperties): SwaggerUiConfigProperties {
+ config.showCommonExtensions = true
+ config.queryConfigEnabled = true
+ return config
+}
+
+
+
+
+
+12.14. How can I ignore some field of model?
+
+
+-
+
You can use the following annotation on the top of the field that you want to hide:
+
+-
+
@Schema(hidden = true)
+
+
+
+
+
+12.15. How can I ignore @AuthenticationPrincipal parameter from spring-security?
+
+
+-
+
A solution workaround would be to use: @Parameter(hidden = true)
+
+-
+
For a project that uses spring-security, you should add the following dependency, in combination with the springdoc-openapi-ui dependency:
+
+
+
+
+
+<dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-security</artifactId>
+ <version>last.version</version>
+</dependency>
+
+
+
+
+12.16. Is there a Gradle plugin available?
+
+
+-
+
Yes. More details are available, in the gradle plugin section.
+
+
+
+
+
+12.17. How can I hide a parameter from the documentation?
+
+
+-
+
You can use @Parameter(hidden = true)
+
+
+
+
+
+
+12.19. Does springdoc-openapi support Jersey?
+
+
+-
+
If you are using JAX-RS and as implementation Jersey (@Path for example), we do not support it.
+
+-
+
We only support exposing Rest Endpoints using Spring managed beans (@RestController for example).
+
+-
+
You can have a look at swagger-jaxrs2 project:
+
+
+
+
+
+
+12.20. Can springdoc-openapi generate API only for @RestController?
+
+
+-
+
@RestController is equivalent to @Controller + @RequestMapping on the type level.
+
+-
+
For some legacy apps, we are constrained to still support both.
+
+-
+
If you need to hide the @Controller on the type level, in this case, you can use: @Hidden on controller level.
+
+-
+
Please note this annotation can be also used to hide some methods from the generated documentation.
+
+
+
+
+
+12.21. Are the following validation annotations supported : @NotEmpty @NotBlank @PositiveOrZero @NegativeOrZero?
+
+
+-
+
Yes
+
+
+
+
+
+12.22. How can I map Pageable (spring-data-commons) object to correct URL-Parameter in Swagger UI?
+
+The support for Pageable of spring-data-commons is available out-of-the box since springdoc-openapi v1.6.0.
+For this, you have to combine @ParameterObject annotation with the Pageable type.
+
+
+Before springdoc-openapi v1.6.0:
+
+
+
+-
+
You can use as well @ParameterObject instead of @PageableAsQueryParam for HTTP GET methods.
+
+
+
+
+
+static {
+ getConfig().replaceParameterObjectWithClass(org.springframework.data.domain.Pageable.class, Pageable.class)
+ .replaceParameterObjectWithClass(org.springframework.data.domain.PageRequest.class, Pageable.class);
+}
+
+
+
+
+
+-
+
Another solution, is to configure Pageable manually:
+
+
+-
+
you will have to declare the explicit mapping of Pageable fields as Query Params and add the @Parameter(hidden = true) Pageable pageable on your pageable parameter.
+
+-
+
You should also, declare the annotation @PageableAsQueryParam provided by springdoc-openapi on the method level, or declare your own if need to define your custom description, defaultValue, …
+
+
+
+
+
+
+
+If you want to disable the support of spring Pageable Type, you can use:
+
+
+
+springdoc.model-converters.pageable-converter.enabled=false
+
+
+
+
+
+
+
+
+
+The property springdoc.model-converters.pageable-converter.enabled is only available since v1.5.11+
+
+
+
+
+
+
+12.23. How can I generate enums in the generated description?
+
+
+-
+
You could add a property allowableValues, to @Parameter. For example:
+
+
+
+
+
+@GetMapping("/example")
+public Object example(@Parameter(name = "json", schema = @Schema(description = "var 1", type = "string", allowableValues = {"1", "2"}))
+String json) {
+ return null;
+}
+
+
+
+
+
+-
+
or you could override toString on your enum:
+
+
+
+
+
+@Override
+@JsonValue
+public String toString() {
+ return String.valueOf(action);
+}
+
+
+
+
+
+12.24. How can I deploy springdoc-openapi-ui behind a reverse proxy?
+
+
+-
+
If your application is running behind a proxy, a load-balancer or in the cloud, the request information (like the host, port, scheme…) might change along the way. Your application may be running on 10.10.10.10:8080, but HTTP clients should only see example.org.
+
+-
+
RFC7239 "Forwarded Headers" defines the Forwarded HTTP header; proxies can use this header to provide information about the original request. You can configure your application to read those headers and automatically use that information when creating links and sending them to clients in HTTP 302 responses, JSON documents or HTML pages. There are also non-standard headers, like X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Proto, X-Forwarded-Ssl, and X-Forwarded-Prefix.
+
+-
+
If the proxy adds the commonly used X-Forwarded-For and X-Forwarded-Proto headers, setting server.forward-headers-strategy to NATIVE is enough to support those. With this option, the Web servers themselves natively support this feature; you can check their specific documentation to learn about specific behavior.
+
+-
+
You need to make sure the following header is set in your reverse proxy configuration: X-Forwarded-Prefix
+
+-
+
For example, using Apache 2, configuration:
+
+
+
+
+
+RequestHeader set X-Forwarded-Prefix "/custom-path"
+
+
+
+
+-
+
Then, in your Spring Boot application make sure your application handles this header: X-Forwarded-For. There are two ways to achieve this:
+
+
+
+
+
+server.use-forward-headers=true
+
+
+
+
+-
+
If this is not enough, Spring Framework provides a ForwardedHeaderFilter. You can register it as a Servlet Filter in your application by setting server.forward-headers-strategy is set to FRAMEWORK.
+
+-
+
Since Spring Boot 2.2, this is the new property to handle reverse proxy headers:
+
+
+
+
+
+server.forward-headers-strategy=framework
+
+
+
+
+-
+
And you can add the following bean to your application:
+
+
+
+
+
+@Bean
+ForwardedHeaderFilter forwardedHeaderFilter() {
+ return new ForwardedHeaderFilter();
+}
+
+
+
+
+
+
+12.26. Adding springdoc-openapi-ui dependency breaks my public/index.html welcome page
+
+
+-
+
If you already have static content on your root, and you don’t want it to be overridden by springdoc-openapi-ui configuration, you can just define a custom configuration of the swagger-ui, in order not to override the configuration of your files from in your context-root:
+
+-
+
For example use:
+
+
+
+
+
+springdoc.swagger-ui.path= /swagger-ui/api-docs.html
+
+
+
+
+12.27. How can I test the Swagger UI?
+
+
+-
+
You can have a look on this sample test of the UI:
+
+
+
+
+
+
+12.28. How can I customise the OpenAPI object?
+
+
+-
+
You can write your own implementation of OpenApiCustomizer.
+
+-
+
An example is available on:
+
+
+
+
+
+
+@Bean
+public OpenApiCustomizer customerGlobalHeaderOpenApiCustomizer() {
+ return openApi -> openApi.getPaths().values().stream().flatMap(pathItem -> pathItem.readOperations().stream())
+ .forEach(operation -> operation.addParametersItem(new HeaderParameter().$ref("#/components/parameters/myGlobalHeader")));
+}
+
+
+
+
+
+
+
+
+
+
+This bean OpenApiCustomizer will be applied to the Default OpenAPI only.
+
+
+
+
+
+If you need the OpenApiCustomizer to applied to GroupedOpenApi as well, then use GlobalOpenApiCustomizer instead.
+
+
+
+12.29. How can I return an empty content as response?
+
+
+-
+
It is be possible to handle as return an empty content as response using, one of the following syntaxes:
+
+-
+
content = @Content
+
+-
+
content = @Content(schema = @Schema(hidden = true))
+
+-
+
For example:
+
+
+
+
+
+@Operation(summary = "Get thing", responses = {
+ @ApiResponse(description = "Successful Operation", responseCode = "200", content = @Content(mediaType = "application/json", schema = @Schema(implementation = String.class))),
+ @ApiResponse(responseCode = "404", description = "Not found", content = @Content),
+ @ApiResponse(responseCode = "401", description = "Authentication Failure", content = @Content(schema = @Schema(hidden = true))) })
+@RequestMapping(path = "/testme", method = RequestMethod.GET)
+ResponseEntity<String> testme() {
+ return ResponseEntity.ok("Hello");
+}
+
+
+
+
+
+12.30. How are endpoints with multiple consuming media types supported?
+
+
+-
+
An overloaded method on the same class, with the same HTTP Method and path, will have as a result, only one OpenAPI Operation generated.
+
+-
+
In addition, it’s recommended to have the @Operation in the level of one of the overloaded methods. Otherwise it might be overridden if it’s declared many times within the same overloaded method.
+
+
+
+
+
+12.31. How can I get yaml and json (OpenAPI) in compile time?
+
+
+-
+
You can use springdoc-openapi-maven-plugin for this functionality:
+
+
+-
+
You can customise the output directory (property outputDir): The default value is: ${project.build.directory}
+
+
+
+
+
+12.32. What are the ignored types in the documentation?
+
+
+-
+
Principal, Locale, HttpServletRequest and HttpServletResponse and other injectable parameters supported by Spring MVC are excluded.
+
+-
+
Full documentation here:
+
+
+
+
+
+
+12.33. How can i disable ignored types:
+
+If you don’t want to ignore the types Principal, Locale, HttpServletRequest, and others,:
+
+
+
+SpringDocUtils.getConfig().removeRequestWrapperToIgnore(HttpServletRequest.class)
+
+
+
+
+
+12.34. How do I add authorization header in requests?
+
+
+-
+
You should add the @SecurityRequirement tags to your protected APIs.
+
+-
+
For example:
+
+
+
+
+
+@Operation(security = { @SecurityRequirement(name = "bearer-key") })
+
+
+
+
+-
+
And the security definition sample:
+
+
+
+
+
+@Bean
+public OpenAPI customOpenAPI() {
+ return new OpenAPI()
+ .components(new Components()
+ .addSecuritySchemes("bearer-key",
+ new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")));
+}
+
+
+
+
+
+12.35. Differentiation to Springfox project
+
+
+-
+
OAS 3 was released in July 2017, and there was no release of springfox to support OAS 3.
+springfox covers for the moment only swagger 2 integration with Spring Boot. The latest release date is June 2018. So, in terms of maintenance there is a big lack of support lately.
+
+-
+
We decided to move forward and share the library that we already used on our internal projects, with the community.
+
+-
+
The biggest difference with springfox, is that we integrate new features not covered by springfox:
+
+-
+
The integration between Spring Boot and OpenAPI 3 standard.
+
+-
+
We rely on on swagger-annotations and swagger-ui only official libraries.
+
+-
+
We support new features on Spring 5, like spring-webflux with annotated and functional style.
+
+-
+
We do our best to answer all the questions and address all issues or enhancement requests
+
+
+
+
+
+12.36. How do I migrate to OpenAPI 3 with springdoc-openapi
+
+
+-
+
There is no relation between springdoc-openapi and springfox.If you want to migrate to OpenAPI 3:
+
+-
+
Remove all the dependencies and the related code to springfox
+
+-
+
Add springdoc-openapi-ui dependency
+
+-
+
If you don’t want to serve the UI from your root path or there is a conflict with an existing configuration, you can just change the following property:
+
+
+
+
+
+springdoc.swagger-ui.path=/you-path/swagger-ui.html
+
+
+
+
+12.37. How can I set a global header?
+
+
+-
+
You may have global parameters with Standard OpenAPI description.
+
+-
+
If you need the definitions to appear globally (within every group), no matter if the group fulfills the conditions specified on the GroupedOpenApi, you can use OpenAPI Bean.
+
+-
+
You can define common parameters under parameters in the global components section and reference them elsewhere via $ref. You can also define global header parameters.
+
+-
+
For this, you can override to OpenAPI Bean, and set the global headers or parameters definition on the components level.
+
+
+
+
+
+@Bean
+public OpenAPI customOpenAPI(@Value("${springdoc.version}") String appVersion) {
+ return new OpenAPI()
+ .components(new Components().addSecuritySchemes("basicScheme", new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic"))
+ .addParameters("myHeader1", new Parameter().in("header").schema(new StringSchema()).name("myHeader1")).addHeaders("myHeader2", new Header().description("myHeader2 header").schema(new StringSchema())))
+ .info(new Info()
+ .title("Petstore API")
+ .version(appVersion)
+ .description("This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.")
+ .termsOfService("http://swagger.io/terms/")
+ .license(new License().name("Apache 2.0").url("http://springdoc.org")));
+}
+
+
+
+
+
+
+12.39. How can I define SecurityScheme?
+
+
+-
+
You can use: @SecurityScheme annotation.
+
+-
+
Or you can define it programmatically, by overriding OpenAPI Bean:
+
+
+
+
+
+@Bean
+public OpenAPI customOpenAPI(@Value("${springdoc.version}") String appVersion) {
+ return new OpenAPI()
+ .components(new Components().addSecuritySchemes("basicScheme",
+ new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic")))
+ .info(new Info().title("SpringShop API").version(appVersion)
+ .license(new License().name("Apache 2.0").url("http://springdoc.org")));
+}
+
+
+
+
+
+12.40. How can I hide an operation or a controller from documentation?
+
+
+-
+
You can use @io.swagger.v3.oas.annotations.Hidden annotation at @RestController, @RestControllerAdvice and method level
+
+-
+
The @Hidden annotation on exception handler methods, is considered when building generic (error) responses from @ControllerAdvice exception handlers.
+
+-
+
Or use: @Operation(hidden = true)
+
+
+
+
+
+12.41. How to configure global security schemes?
+
+
+-
+
For global SecurityScheme, you can add it inside your own OpenAPI definition:
+
+
+
+
+
+@Bean
+public OpenAPI customOpenAPI() {
+ return new OpenAPI().components(new Components()
+ .addSecuritySchemes("basicScheme", new SecurityScheme()
+ .type(SecurityScheme.Type.HTTP).scheme("basic"))).info(new Info().title("Custom API")
+ .version("100")).addTagsItem(new Tag().name("mytag"));
+}
+
+
+
+
+
+12.42. Can I use spring property with swagger annotations?
+
+
+-
+
The support of spring property resolver for @Info: title * description * version * termsOfService
+
+-
+
The support of spring property resolver for @Info.license: name * url
+
+-
+
The support of spring property resolver for @Info.contact: name * email * url
+
+-
+
The support of spring property resolver for @Operation: description * summary
+
+-
+
The support of spring property resolver for @Parameter: description * name
+
+-
+
The support of spring property resolver for @ApiResponse: description
+
+-
+
Its also possible to declare security URLs for @OAuthFlow: openIdConnectUrl * authorizationUrl * refreshUrl * tokenUrl
+
+-
+
The support of spring property resolver for @Schema: name * title * description , by setting springdoc.api-docs.resolve-schema-properties to true
+
+
+
+
+
+12.43. How is server URL generated?
+
+
+-
+
Generating automatically server URL may be useful, if the documentation is not present.
+
+-
+
If the server annotations are present, they will be used instead.
+
+
+
+
+
+12.44. How can I disable springdoc-openapi cache?
+
+
+-
+
By default, the OpenAPI description is calculated once, and then cached.
+
+-
+
Sometimes the same swagger-ui is served behind internal and external proxies. some users want the server URL, to be computed on each http request.
+
+-
+
In order to disable springdoc cache, you will have to set the following property:
+
+
+
+
+
+springdoc.cache.disabled= true
+
+
+
+
+12.45. How can I expose the mvc api-docs endpoints without using the swagger-ui?
+
+
+-
+
You should use the springdoc-openapi-core dependency only:
+
+
+
+
+
+<dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-webmvc-core</artifactId>
+ <version>latest.version</version>
+</dependency>
+
+
+
+
+12.46. How can I disable springdoc-openapi endpoints?
+
+
+-
+
Use the following property:
+
+
+
+
+
+springdoc.api-docs.enabled=false
+
+
+
+
+12.47. How can I hide Schema of the the response?
+
+
+-
+
To hide the response element, using @Schema annotation, as follows, at operation level:
+
+
+
+
+
+@Operation(responses = @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(hidden = true))))
+
+
+
+
+-
+
Or directly at @ApiResponses level:
+
+
+
+
+
+@ApiResponses(value = {@ApiResponse(responseCode = "200", content = @Content(schema = @Schema(hidden = true))) })
+OR
+@ApiResponse(responseCode = "404", description = "Not found", content = @Content)
+
+
+
+
+12.48. What is the URL of the swagger-ui, when I set a different context-path?
+
+
+-
+
If you use different context-path:
+
+
+
+
+
+server.servlet.context-path= /foo
+
+
+
+
+-
+
The swagger-ui will be available on the following URL:
+
+
+-
+
http://server:port/foo/swagger-ui.html
+
+
+
+
+
+
+
+
+12.49. Can I customize OpenAPI object programmatically?
+
+
+-
+
You can Define your own OpenAPI Bean: If you need the definitions to appear globally (within every group), no matter if the group fulfills the conditions specified on the GroupedOpenApi, you can use OpenAPI Bean.
+
+
+
+
+
+@Bean
+public OpenAPI customOpenAPI(@Value("${springdoc.version}") String appVersion) {
+ return new OpenAPI()
+ .components(new Components().addSecuritySchemes("basicScheme",
+ new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic")))
+ .info(new Info().title("SpringShop API").version(appVersion)
+ .license(new License().name("Apache 2.0").url("http://springdoc.org")));
+}
+
+
+
+
+
+-
+
If you need the definitions to appear within a specific group, and respect the conditions specified on the GroupedOpenApi, you can add OpenApiCustomiser to your GroupedOpenApi definition.
+
+
+
+
+
+GroupedOpenApi.builder().group("users").pathsToMatch(paths).packagesToScan(packagedToMatch).addOpenApiCustomiser(customerGlobalHeaderOpenApiCustomiser())
+ .build()
+
+@Bean
+public OpenApiCustomiser customerGlobalHeaderOpenApiCustomiser() {
+ return openApi -> openApi.path("/foo",
+ new PathItem().get(new Operation().operationId("foo").responses(new ApiResponses()
+ .addApiResponse("default", new ApiResponse().description("")
+ .content(new Content().addMediaType("fatz", new MediaType()))))));
+}
+
+
+
+
+
+12.50. Where can I find the source code of the demo applications?
+
+
+-
+
The source code of the application is available at the following GitHub repository:
+
+
+
+
+
+
+
+
+12.53. Is file upload supported?
+
+
+-
+
The library supports the main file types: MultipartFile, @RequestPart, FilePart
+
+
+
+
+
+
+12.55. Why my parameter is marked as required?
+
+
+-
+
Any @GetMapping parameters is marked as required, even if @RequestParam is missing.
+
+-
+
You can add @Parameter(required=false) annotation if you need different behaviour.
+
+-
+
Query parameters with defaultValue specified are marked as required.
+
+
+
+
+
+12.56. How are overloaded methods with the same endpoints, but with different parameters
+
+
+-
+
springdoc-openapi renders these methods as a single endpoint. It detects the overloaded endpoints, and generates parameters.schema.oneOf.
+
+
+
+
+
+12.57. What is a proper way to set up Swagger UI to use provided spec.yml?
+
+
+-
+
With this property, all the springdoc-openapi auto-configuration beans are disabled:
+
+
+
+
+
+springdoc.api-docs.enabled=false
+
+
+
+
+-
+
Then enable the minimal Beans configuration, by adding this Bean:
+
+
+
+
+
+@Bean
+SpringDocConfiguration springDocConfiguration(){
+ return new SpringDocConfiguration();
+}
+
+@Bean
+SpringDocConfigProperties springDocConfigProperties() {
+ return new SpringDocConfigProperties();
+}
+
+@Bean
+ObjectMapperProvider objectMapperProvider(SpringDocConfigProperties springDocConfigProperties){
+ return new ObjectMapperProvider(springDocConfigProperties);
+}
+
+
+
+
+
+-
+
Then configure, the path of your custom UI yaml file.
+
+
+
+
+
+springdoc.swagger-ui.url=/api-docs.yaml
+
+
+
+
+12.58. Is there a way to send authorization header through the @Parameter tag?
+
+
+-
+
The OpenAPI 3 specification does not allow explicitly adding Authorization header.
+Note: Header parameters named Accept, Content-Type and Authorization are not allowed. To describe these headers
+
+-
+
For more information, you can read:
+
+
+
+
+
+
+12.59. My Rest Controller using @Controller annotation is ignored?
+
+
+-
+
This is the default behaviour if your @Controller doesn’t have annotation @ResponseBody
+
+-
+
You can change your controllers to @RestControllers. Or add @ResponseBody + @Controller.
+
+-
+
If its not possible, you can configure springdoc to scan you additional controller using SpringDocUtils. For example:
+
+
+
+
+
+static {
+ SpringDocUtils.getConfig().addRestControllers(HelloController.class);
+}
+
+
+
+
+
+12.60. How can I define groups using application.yml?
+
+
+-
+
You can load groups dynamically using spring-boot configuration files.
+
+-
+
Note that, for this usage, you don’t have to declare the GroupedOpenApi Bean.
+
+-
+
You need to declare the following properties, under the prefix springdoc.group-configs.
+
+-
+
For example:
+
+
+
+
+
+springdoc.group-configs[0].group=users
+springdoc.group-configs[0].paths-to-match=/user/**
+springdoc.group-configs[0].packages-to-scan=test.org.springdoc.api
+
+
+
+
+-
+
The list of properties under this prefix, are available here:
+
+
+-
+
+
+
+
+
+
+
+
+
+12.61. How can I extract fields from parameter object?
+
+
+-
+
You can use springdoc annotation @ParameterObject.
+
+-
+
Request parameter annotated with @ParameterObject will help adding each field of the parameter as a separate request parameter.
+
+-
+
This is compatible with Spring MVC request parameters mapping to POJO object.
+
+-
+
This annotation does not support nested parameter objects.
+
+-
+
POJO object must contain getters for fields with mandatory prefix get. Otherwise, the swagger documentation will not show the fields of the annotated entity.
+
+
+
+
+
+12.62. How to Integrate Open API 3 with Spring project (not Spring Boot)?
+
+When your application is using spring without (spring-boot), you need to add beans and auto-configuration that are natively provided in spring-boot.
+
+
+For example, lets assume you want load the swagger-ui in spring-mvc application:
+
+
+
+-
+
You mainly, need to add the springdoc-openapi module
+
+
+
+
+
+<dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-ui</artifactId>
+ <version>last.version</version>
+</dependency>
+
+
+
+
+-
+
If you don’t have the spring-boot and spring-boot-autoconfigure dependencies, you need to add them. And pay attention to the compatibility matrix, between you spring.version and spring-boot.version. For example, in this case (spring.version=5.1.12.RELEASE):
+
+
+
+
+
+<dependency>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot</artifactId>
+ <version>2.1.11.RELEASE</version>
+</dependency>
+<dependency>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-autoconfigure</artifactId>
+ <version>2.1.11.RELEASE</version>
+</dependency>
+
+
+
+
+-
+
Scan for the springdoc-openapi 'auto-configuration classes that spring-boot automatically loads for you.
+
+-
+
Depending on your module, you can find them on the file: spring.factories of each springdoc-openapi module.
+
+
+
+
+
+@EnableWebMvc
+public class AppInitializer implements WebApplicationInitializer {
+
+ @Override
+ public void onStartup(ServletContext servletContext) throws ServletException {
+ WebApplicationContext context = getContext();
+ servletContext.addListener(new ContextLoaderListener(context));
+ ServletRegistration.Dynamic dispatcher = servletContext.addServlet("RestServlet",
+ new DispatcherServlet(context));
+ dispatcher.setLoadOnStartup(1);
+ dispatcher.addMapping("/*");
+ }
+
+ private AnnotationConfigWebApplicationContext getContext() {
+ AnnotationConfigWebApplicationContext context = new AnnotationConfigWebApplicationContext();
+ context.scan("rest");
+ context.register(this.getClass(), org.springdoc.webmvc.ui.SwaggerConfig.class,
+ org.springdoc.core.SwaggerUiConfigProperties.class, org.springdoc.core.SwaggerUiOAuthProperties.class,
+ org.springdoc.webmvc.core.SpringDocWebMvcConfiguration.class,
+ org.springdoc.webmvc.core.MultipleOpenApiSupportConfiguration.class,
+ org.springdoc.core.SpringDocConfiguration.class, org.springdoc.core.SpringDocConfigProperties.class,
+ org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration.class);
+
+ return context;
+ }
+}
+
+
+
+
+
+-
+
Depending on your module, you can find them on the file: spring.factories of each springdoc-openapi module.
+
+-
+
For groups usage make sure your GroupedOpenApi Beans are scanned.
+
+-
+
If additionally, you are using custom context path: /my-servlet-path. Make sure you declare the following property:
+
+
+
+
+
+spring.mvc.servlet.path=/my-servlet-path
+
+
+
+
+12.63. How can I use the last springdoc-openapi SNAPSHOT ?
+
+
+-
+
For testing purposes only, you can test temporarily using the last springdoc-openapi SNAPSHOT
+
+-
+
To achieve that, configure your pom.xml file with the following <repositories> section:
+
+
+
+
+
+ <repositories>
+ <repository>
+ <name>Central Portal Snapshots</name>
+ <id>central-portal-snapshots</id>
+ <url>https://central.sonatype.com/repository/maven-snapshots/</url>
+ <releases>
+ <enabled>false</enabled>
+ </releases>
+ <snapshots>
+ <enabled>true</enabled>
+ </snapshots>
+ </repository>
+ </repositories>
+
+
+
+
+12.64. How can I use enable springdoc-openapi MonetaryAmount support?
+
+
+-
+
If an application wants to enable the springdoc-openapi support, it declares:
+
+
+
+
+
+SpringDocUtils.getConfig().replaceWithClass(MonetaryAmount.class, org.springdoc.core.converters.models.MonetaryAmount.class);
+
+
+
+
+
+-
+
Another solution, without using springdoc-openapi MonetaryAmount, would be:
+
+
+
+
+
+SpringDocUtils.getConfig().replaceWithSchema(MonetaryAmount.class, new ObjectSchema()
+ .addProperties("amount", new NumberSchema()).example(99.96)
+ .addProperties("currency", new StringSchema().example("USD")));
+
+
+
+
+
+12.65. How can i aggregate external endpoints (exposing OPENAPI 3 spec) inside one single application?
+
+The properties springdoc.swagger-ui.urls.*, are suitable to configure external (/v3/api-docs url).
+For example, if you want to aggregate all the endpoints of other services, inside one single application.
+IMPORTANT: Don’t forget that CORS needs to be enabled as well.
+
+
+
+12.66. How can use custom json/yml file instead of generated one?
+
+If your file open-api.json, contains the OpenAPI documentation in OpenAPI 3 format.
+Then simply declare: The file name can be anything you want, from the moment your declaration is consistent yaml or json OpenAPI Spec.
+
+
+
+ springdoc.swagger-ui.url=/open-api.json
+
+
+
+Then the file open-api.json, should be located in: src/main/resources/static
+No additional configuration is needed.
+
+
+
+12.67. How can i enable CSRF support?
+
+If you are using standard headers. (For example, using spring-security headers)
+If the CSRF Token is required, swagger-ui automatically sends the new XSRF-TOKEN during each HTTP REQUEST.
+
+
+If your XSRF-TOKEN isn’t standards-based, you can use a requestInterceptor to manually capture and attach the latest xsrf token to requests programmatically via spring resource transformer:
+
+
+
+
+
+Starting from release v1.4.4 of springdoc-openapi, a new property is added to enable CSRF support, while using standard header names:
+
+
+
+springdoc.swagger-ui.csrf.enabled=true
+
+
+
+
+12.68. How can i disable the default swagger petstore URL?
+
+You can use the following property:
+
+
+
+springdoc.swagger-ui.disable-swagger-default-url=true
+
+
+
+
+12.69. Is @PageableDefault supported, to enhance the OpenAPI 3 documentation?
+
+Yes, you can use it in conjunction with @ParameterObject annotation.
+Also, the spring-boot spring.data.web. and spring.data.rest.default. properties are supported since v1.4.5
+
+
+
+12.70. How can I make spring security login-endpoint visible?
+
+You can use the following property:
+
+
+
+springdoc.show-login-endpoint=true
+
+
+
+
+12.71. How can I show schema definitions even if the schema is not referenced?
+
+You can use the following property:
+
+
+
+springdoc.remove-broken-reference-definitions=false
+
+
+
+
+12.72. How to override @Deprecated?
+
+The whole idea of springdoc-openapi is to get your documentation the closest to the code, with minimal code changes.
+If the code contains @Deprecated, sprindoc-openapi will consider its schema as Deprecated as well.
+If you want to declare a field on swagger as non deprecated, even with the java code, the field contains @Depreacted,
+You can use the following property that is available since release v1.4.3:
+
+
+
+springdoc.model-converters.deprecating-converter.enabled=false
+
+
+
+
+12.73. How can i display a method that returns ModelAndView?
+
+You can use the following property:
+
+
+
+springdoc.model-and-view-allowed=true
+
+
+
+
+12.74. How can i have pretty-printed output of the OpenApi specification?
+
+You can use the following property:
+
+
+
+springdoc.writer-with-default-pretty-printer=true
+
+
+
+
+12.75. How can i define different schemas for the same class?
+
+Complex objects are always resolved as a reference to a schema defined in components.
+For example, let’s consider a Instance class with an workAddress and homeAddress attribute of type Address:
+
+
+
+public class PersonDTO {
+
+ @JsonProperty
+ private String email;
+
+ @JsonProperty
+ private String firstName;
+
+ @JsonProperty
+ private String lastName;
+
+ @Schema(ref = "WorkAddressSchema")
+ @JsonProperty
+ private Address workAddress;
+
+ @Schema(ref = "HomeAddressSchema")
+ @JsonProperty
+ private Address homeAddress;
+
+}
+
+public class Address {
+
+ @JsonProperty
+ private String addressName;
+
+}
+
+
+
+
+If you want to define two different schemas for this class, you can set up 2 different schemas as follow:
+
+
+
+@Bean
+public OpenAPI customOpenAPI() {
+ return new OpenAPI().components(new Components()
+ .addSchemas("WorkAddressSchema", getSchemaWithDifferentDescription(Address.class, "work Address"))
+ .addSchemas("HomeAddressSchema", getSchemaWithDifferentDescription(Address.class, "home Address")));
+}
+
+private Schema getSchemaWithDifferentDescription(Class className, String description) {
+ ResolvedSchema resolvedSchema = ModelConverters.getInstance()
+ .resolveAsResolvedSchema(
+ new AnnotatedType(className).resolveAsRef(false));
+ return resolvedSchema.schema.description(description);
+}
+
+
+
+
+
+12.76. How can i define different description for a class attribute depending on usage?
+
+For example, let’s consider a Instance class with an email attribute:
+
+
+
+public class PersonDTO {
+
+ @JsonProperty
+ private String email;
+
+ @JsonProperty
+ private String firstName;
+
+ @JsonProperty
+ private String lastName;
+
+
+}
+
+
+
+
+If you want to define two different description for the email, you can set up 2 different schemas as follow:
+
+
+
+@Bean
+public OpenAPI customOpenAPI() {
+ return new OpenAPI().components(new Components()
+ .addSchemas("PersonDTO1", getFieldSchemaWithDifferentDescription(PersonDTO.class, "work email"))
+ .addSchemas("PersonDTO2", getFieldSchemaWithDifferentDescription(PersonDTO.class, "home email")));
+}
+
+private Schema getFieldSchemaWithDifferentDescription(Class className, String description) {
+ ResolvedSchema resolvedSchema = ModelConverters.getInstance()
+ .resolveAsResolvedSchema(
+ new AnnotatedType(className).resolveAsRef(false));
+ return resolvedSchema.schema.addProperties("email", new StringSchema().description(description));
+}
+
+
+
+
+
+12.77. Customizing swagger static resources
+
+You can customize swagger documentation static resources located in META-INF/resources/webjars/swagger-ui/{swagger.version}/. The list of resources includes:
+
+
+
+-
+
index.html
+
+-
+
swagger-ui-bundle.js
+
+-
+
swagger-ui.css
+
+-
+
swagger-ui-standalone-preset.js
+
+-
+
swagger-ui.css.map
+
+-
+
swagger-ui-bundle.js.map
+
+-
+
swagger-ui-standalone-preset.js.map
+
+-
+
favicon-32x32.png
+
+
+
+
+To do this, you need to extend the implementation of SwaggerIndexPageTransformer
+
+
+
+public class SwaggerCodeBlockTransformer
+ extends SwaggerIndexPageTransformer {
+ // < constructor >
+ @Override
+ public Resource transform(HttpServletRequest request,
+ Resource resource,
+ ResourceTransformerChain transformer)
+ throws IOException {
+ if (resource.toString().contains("swagger-ui.css")) {
+ final InputStream is = resource.getInputStream();
+ final InputStreamReader isr = new InputStreamReader(is);
+ try (BufferedReader br = new BufferedReader(isr)) {
+ final String css = br.lines().collect(Collectors.joining());
+ final byte[] transformedContent = css.replace("old", "new").getBytes();
+ return new TransformedResource(resource, transformedContent);
+ } // AutoCloseable br > isr > is
+ }
+ return super.transform(request, resource, transformer);
+ }
+
+}
+
+
+
+
+Next, add transformer @Bean to your @Configuration
+
+
+
+@Configuration
+public class OpenApiConfig {
+ @Bean
+ public SwaggerIndexTransformer swaggerIndexTransformer(
+ SwaggerUiConfigProperties a,
+ SwaggerUiOAuthProperties b,
+ SwaggerUiConfigParameters c,
+ SwaggerWelcomeCommon d) {
+ return new SwaggerCodeBlockTransformer(a, b, c, d);
+ }
+}
+
+
+
+
+Illustrative example
+
+
+
+
+
+
+
+
+12.78. What is the compatibility matrix of springdoc-openapi with spring-boot ?
+
+springdoc-openapi is compatible with spring-boot 1 and spring-boot 2.
+
+
+In general, you should only pick the last stable version as per today 1.8.0.
+
+
+More precisely, this the exhaustive list of spring-boot versions against which springdoc-openapi has been built:
+
+
+
+
+
+
+spring-boot Versions
+Minimum springdoc-openapi Versions
+
+
+
+
+3.0.x
2.0.x+
+
+2.7.x, 1.5.x
1.6.11+
+
+2.6.x, 1.5.x
1.6.0+
+
+2.5.x, 1.5.x
1.5.9+
+
+2.4.x, 1.5.x
1.5.0+
+
+2.3.x, 1.5.x
1.4.0+
+
+2.2.x, 1.5.x
1.2.1+
+
+2.0.x, 1.5.x
1.0.0+
+
+
+
+
+12.79. Why am i getting an error: Swagger UI unable to render definition, when overriding the default spring registered HttpMessageConverter?
+
+When overriding the default spring-boot registered HttpMessageConverter, you should have ByteArrayHttpMessageConverter registered as well to have proper springdoc-openapi support.
+
+
+
+ converters.add(new ByteArrayHttpMessageConverter());
+ converters.add(new MappingJackson2HttpMessageConverter(jacksonBuilder.build()));
+
+
+
+
+
+
+
+
+
+
+Order is very important, when registering HttpMessageConverters.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 
+