# Using OpenAPI and Swagger UI

This guide explains how your Quarkus application can expose its API description through an OpenAPI specification and how you can test it via a user-friendly UI named Swagger UI.

## Prerequisites

To complete this guide, you need:

- Roughly 15 minutes

- An IDE

- JDK 17+ installed with `JAVA_HOME` configured appropriately

- Apache Maven 3.9.9

- Optionally the Quarkus CLI if you want to use it

- Optionally Mandrel or GraalVM installed and configured appropriately if you want to build a native executable (or Docker if you use a native container build)

## Architecture

In this guide, we create a straightforward REST application to demonstrate how fast you can expose your API specification and benefit from a user interface to test it.

## Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can skip right to the completed example.

Clone the Git repository: `git clone https://github.com/quarkusio/quarkus-quickstarts.git`, or download an archive.

The solution is located in the `openapi-swaggerui-quickstart` directory.

## Creating the Maven project

First, we need a new project. Create a new project with the following command:

CLI

    quarkus create app org.acme:openapi-swaggerui-quickstart \
        --extension='rest-jackson' \
        --no-code
    cd openapi-swaggerui-quickstart

To create a Gradle project, add the `--gradle` or `--gradle-kotlin-dsl` option.

For more information about how to install and use the Quarkus CLI, see the Quarkus CLI guide.

Maven

    mvn io.quarkus.platform:quarkus-maven-plugin:3.26.0.CR1:create \
        -DprojectGroupId=org.acme \
        -DprojectArtifactId=openapi-swaggerui-quickstart \
        -Dextensions='rest-jackson' \
        -DnoCode
    cd openapi-swaggerui-quickstart

To create a Gradle project, add the `-DbuildTool=gradle` or `-DbuildTool=gradle-kotlin-dsl` option.

For Windows users:

- If using cmd, (don’t use backward slash `\` and put everything on the same line)

- If using Powershell, wrap `-D` parameters in double quotes e.g. `"-DprojectArtifactId=openapi-swaggerui-quickstart"`

## Expose a REST Resource

We will create a `Fruit` bean and a `FruitResource` REST resource (feel free to take a look to the Writing JSON REST services guide if your want more details on how to build a REST API with Quarkus).

    package org.acme.openapi.swaggerui;

    public class Fruit {

        public String name;
        public String description;

        public Fruit() {
        }

        public Fruit(String name, String description) {
            this.name = name;
            this.description = description;
        }
    }

    package org.acme.openapi.swaggerui;

    import jakarta.ws.rs.GET;
    import jakarta.ws.rs.POST;
    import jakarta.ws.rs.DELETE;
    import jakarta.ws.rs.Path;
    import java.util.Collections;
    import java.util.LinkedHashMap;
    import java.util.Set;

    @Path("/fruits")
    public class FruitResource {

        private Set<Fruit> fruits = Collections.newSetFromMap(Collections.synchronizedMap(new LinkedHashMap<>()));

        public FruitResource() {
            fruits.add(new Fruit("Apple", "Winter fruit"));
            fruits.add(new Fruit("Pineapple", "Tropical fruit"));
        }

        @GET
        public Set<Fruit> list() {
            return fruits;
        }

        @POST
        public Set<Fruit> add(Fruit fruit) {
            fruits.add(fruit);
            return fruits;
        }

        @DELETE
        public Set<Fruit> delete(Fruit fruit) {
            fruits.removeIf(existingFruit -> existingFruit.name.contentEquals(fruit.name));
            return fruits;
        }
    }

You can also create a test:

    package org.acme.openapi.swaggerui;

    import io.quarkus.test.junit.QuarkusTest;
    import org.junit.jupiter.api.Test;

    import jakarta.ws.rs.core.MediaType;

    import static io.restassured.RestAssured.given;
    import static org.hamcrest.CoreMatchers.is;
    import static org.hamcrest.Matchers.containsInAnyOrder;

    @QuarkusTest
    public class FruitResourceTest {

        @Test
        public void testList() {
            given()
                    .when().get("/fruits")
                    .then()
                    .statusCode(200)
                    .body("$.size()", is(2),
                            "name", containsInAnyOrder("Apple", "Pineapple"),
                            "description", containsInAnyOrder("Winter fruit", "Tropical fruit"));
        }

        @Test
        public void testAdd() {
            given()
                    .body("{\"name\": \"Pear\", \"description\": \"Winter fruit\"}")
                    .header("Content-Type", MediaType.APPLICATION_JSON)
                    .when()
                    .post("/fruits")
                    .then()
                    .statusCode(200)
                    .body("$.size()", is(3),
                            "name", containsInAnyOrder("Apple", "Pineapple", "Pear"),
                            "description", containsInAnyOrder("Winter fruit", "Tropical fruit", "Winter fruit"));

            given()
                    .body("{\"name\": \"Pear\", \"description\": \"Winter fruit\"}")
                    .header("Content-Type", MediaType.APPLICATION_JSON)
                    .when()
                    .delete("/fruits")
                    .then()
                    .statusCode(200)
                    .body("$.size()", is(2),
                            "name", containsInAnyOrder("Apple", "Pineapple"),
                            "description", containsInAnyOrder("Winter fruit", "Tropical fruit"));
        }
    }

## Expose OpenAPI Specifications

Quarkus provides the SmallRye OpenAPI extension compliant with the MicroProfile OpenAPI specification in order to generate your API OpenAPI v3 specification.

You just need to add the `openapi` extension to your Quarkus application:

CLI

    quarkus extension add quarkus-smallrye-openapi

Maven

    ./mvnw quarkus:add-extension -Dextensions='quarkus-smallrye-openapi'

Gradle

    ./gradlew addExtension --extensions='quarkus-smallrye-openapi'

This will add the following to your build file:

pom.xml

    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-smallrye-openapi</artifactId>
    </dependency>

build.gradle

    implementation("io.quarkus:quarkus-smallrye-openapi")

Now, we are ready to run our application:

CLI

    quarkus dev

Maven

    ./mvnw quarkus:dev

Gradle

    ./gradlew --console=plain quarkusDev

Once your application is started, you can make a request to the default `/q/openapi` endpoint:

    $ curl http://localhost:8080/q/openapi
    openapi: 3.1.0
    info:
      title: Generated API
      version: "1.0"
    paths:
      /fruits:
        get:
          responses:
            200:
              description: OK
              content:
                application/json: {}
        post:
          requestBody:
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Fruit'
          responses:
            200:
              description: OK
              content:
                application/json: {}
        delete:
          requestBody:
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Fruit'
          responses:
            200:
              description: OK
              content:
                application/json: {}
    components:
      schemas:
        Fruit:
          properties:
            description:
              type: string
            name:
              type: string

| If you do not like the default endpoint location `/q/openapi`, you can change it by adding the following configuration to your `application.properties`:
    quarkus.smallrye-openapi.path=/swagger

| You can request the OpenAPI in JSON format using the `format` query parameter. For example:
    /q/openapi?format=json

Hit `CTRL+C` to stop the application.

## Providing Application Level OpenAPI Annotations

There are some MicroProfile OpenAPI annotations which describe global API information, such as the following:

- API Title

- API Description

- Version

- Contact Information

- License

All of this information (and more) can be included in your Java code by using appropriate OpenAPI annotations on a Jakarta REST `Application` class. Because a Jakarta REST `Application` class is not required in Quarkus, you will likely have to create one. It can simply be an empty class that extends `jakarta.ws.rs.core.Application`. This empty class can then be annotated with various OpenAPI annotations such as `@OpenAPIDefinition`. For example:

    @OpenAPIDefinition(
        tags = {
                @Tag(name="widget", description="Widget operations."),
                @Tag(name="gasket", description="Operations related to gaskets")
        },
        info = @Info(
            title="Example API",
            version = "1.0.1",
            contact = @Contact(
                name = "Example API Support",
                url = "http://exampleurl.com/contact",
                email = "techsupport@example.com"),
            license = @License(
                name = "Apache 2.0",
                url = "https://www.apache.org/licenses/LICENSE-2.0.html"))
    )
    public class ExampleApiApplication extends Application {
    }

Another option, that is a feature provided by SmallRye and not part of the specification, is to use configuration to add this global API information. This way, you do not need to have a Jakarta REST `Application` class, and you can name the API differently per environment.

For example, add the following to your `application.properties`:

    quarkus.smallrye-openapi.info-title=Example API
    %dev.quarkus.smallrye-openapi.info-title=Example API (development)
    %test.quarkus.smallrye-openapi.info-title=Example API (test)
    quarkus.smallrye-openapi.info-version=1.0.1
    quarkus.smallrye-openapi.info-description=Just an example service
    quarkus.smallrye-openapi.info-terms-of-service=Your terms here
    quarkus.smallrye-openapi.info-contact-email=techsupport@example.com
    quarkus.smallrye-openapi.info-contact-name=Example API Support
    quarkus.smallrye-openapi.info-contact-url=http://exampleurl.com/contact
    quarkus.smallrye-openapi.info-license-name=Apache 2.0
    quarkus.smallrye-openapi.info-license-url=https://www.apache.org/licenses/LICENSE-2.0.html

This will give you similar information as the `@OpenAPIDefinition` example above.

## Enhancing the OpenAPI Schema with Filters

You can change the Generated OpenAPI Schema using one or more filter. Filters can run during build time, or at runtime.

    /**
     * Filter to add custom elements
     */
    @OpenApiFilter(OpenApiFilter.RunStage.BUILD) (1)
    public class MyBuildTimeFilter implements OASFilter { (2)

        private IndexView view;

        public MyBuildTimeFilter(IndexView view) { (3)
            this.view = view;
        }

        @Override
        public void filterOpenAPI(OpenAPI openAPI) { (4)
            Collection<ClassInfo> knownClasses = this.view.getKnownClasses();
            Info info = OASFactory.createInfo();
            info.setDescription("Created from Annotated Buildtime filter with " + knownClasses.size() + " known indexed classes");
            openAPI.setInfo(info);
        }

    }

1 | Annotate method with `@OpenApiFilter` and the run stage (BUILD,RUN,BOTH)
2 | Implement OASFilter and override any of the methods
3 | For Build stage filters, the index can be passed in (optional)
4 | Get a hold of the generated `OpenAPI` Schema, and enhance as required

Remember that setting fields on the schema will override what has been generated, you might want to get and add to (so modify). Also know that the generated values might be null, so you will have to check for that.

### Runtime filters

Runtime filters by default runs on startup (when the final OpenAPI document gets created). You can change runtime filters to run on every request, making the OpenAPI document dynamic. To do this you need to set this propery: `quarkus.smallrye-openapi.always-run-filter=true`.

## Loading OpenAPI Schema From Static Files

Instead of dynamically creating OpenAPI schemas from annotation scanning, Quarkus also supports serving static OpenAPI documents. The static file to serve must be a valid document conforming to the OpenAPI specification. An OpenAPI document that conforms to the OpenAPI Specification is itself a valid JSON object, that can be represented in `yaml` or `json` formats.

To see this in action, we’ll put OpenAPI documentation under `META-INF/openapi.yaml` for our `/fruits` endpoints. Quarkus also supports alternative OpenAPI document paths if you prefer.

    openapi: 3.1.0
    info:
      title: Static OpenAPI document of fruits resource
      description: Fruit resources Open API documentation
      version: "1.0"

    servers:
      - url: http://localhost:8080/q/openapi
        description: Optional dev mode server description

    paths:
      /fruits:
        get:
          responses:
            200:
              description: OK - fruits list
              content:
                application/json: {}
        post:
          requestBody:
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Fruit'
          responses:
            200:
              description: new fruit resource created
              content:
                application/json: {}
        delete:
          requestBody:
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Fruit'
          responses:
            200:
              description: OK - fruit resource deleted
              content:
                application/json: {}
    components:
      schemas:
        Fruit:
          properties:
            description:
              type: string
            name:
              type: string

By default, a request to `/q/openapi` will serve the combined OpenAPI document from the static file and the model generated from application endpoints code. We can however change this to only serve the static OpenAPI document by adding `mp.openapi.scan.disable=true` configuration into `application.properties`.

Now, a request to `/q/openapi` endpoint will serve the static OpenAPI document instead of the generated one.

| About OpenAPI document paths Quarkus supports various paths to store your OpenAPI document under. We recommend you place it under `META-INF/openapi.yml`. Alternative paths are: `META-INF/openapi.yaml` `META-INF/openapi.yml` `META-INF/openapi.json` `WEB-INF/classes/META-INF/openapi.yml` `WEB-INF/classes/META-INF/openapi.yaml` `WEB-INF/classes/META-INF/openapi.json` Live reload of static OpenAPI document is supported during development. A modification to your OpenAPI document will be picked up on fly by Quarkus.

## Changing the OpenAPI version

By default, when the document is generated, the OpenAPI version used will be `3.1.0`. If you use a static file as mentioned above, the version in the file will be used. You can also define the version in SmallRye using the following configuration:

    mp.openapi.extensions.smallrye.openapi=3.0.4

This might be useful if your API goes through a Gateway that needs a certain version.

| Changing the OpenAPI version between `3.0.x` and `3.1.x` versions will result in changes to the rendered document to satisfy the requirements of the chosen version. A good starting point to learn about the differences between OpenAPI 3.0 and 3.1 is the OpenAPI Initiative.

## Auto-generation of Operation Id

The Operation Id can be set using the `@Operation` annotation, and is in many cases useful when using a tool to generate a client stub from the schema. The Operation Id is typically used for the method name in the client stub. In SmallRye, you can auto-generate this Operation Id by using the following configuration:

    mp.openapi.extensions.smallrye.operationIdStrategy=METHOD

Now you do not need to use the `@Operation` annotation. While generating the document, the method name will be used for the Operation Id.

Table 1. The strategies available for generating the Operation Id
Property value | Description
--- | ---
`METHOD` | Use the method name.
`CLASS_METHOD` | Use the class name (without the package) plus the method.
`PACKAGE_CLASS_METHOD` | Use the class name plus the method name.

## Use Swagger UI for development

When building APIs, developers want to test them quickly. Swagger UI is a great tool permitting to visualize and interact with your APIs. The UI is automatically generated from your OpenAPI specification.

The Quarkus `smallrye-openapi` extension comes with a `swagger-ui` extension embedding a properly configured Swagger UI page.

| By default, Swagger UI is only available when Quarkus is started in dev or test mode. If you want to make it available in production too, you can include the following configuration in your `application.properties`:
    quarkus.swagger-ui.always-include=true
This is a build time property, it cannot be changed at runtime after your application is built.

By default, Swagger UI is accessible at `/q/swagger-ui`.

You can update the `/swagger-ui` sub path by setting the `quarkus.swagger-ui.path` property in your `application.properties`:

    quarkus.swagger-ui.path=my-custom-path

| The value `/` is not allowed as it blocks the application from serving anything else. A value prefixed with '/' makes it absolute and not relative.

Now, we are ready to run our application:

    ./mvnw quarkus:dev

You can check the Swagger UI path in your application’s log:

    00:00:00,000 INFO  [io.qua.swa.run.SwaggerUiServletExtension] Swagger UI available at /q/swagger-ui

Once your application is started, you can go to http://localhost:8080/q/swagger-ui and play with your API.

You can visualize your API’s operations and schemas.

You can also interact with your API in order to quickly test it.

Hit `CTRL+C` to stop the application.

### Styling

You can style the swagger ui by supplying your own logo and css.

#### Logo

To supply your own logo, you need to place a file called `logo.png` in `src/main/resources/META-INF/branding`.

This will set the logo for all UIs (not just swagger ui), so in this case also GraphQL-UI and Health-UI (if included).

If you only want to apply this logo to swagger-ui (and not globally to all UIs) call the file `smallrye-open-api-ui.png` rather than `logo.png`.

#### CSS

To supply your own css that override/enhance style in the html, you need to place a file called `style.css` in `src/main/resources/META-INF/branding`.

This will add that css to all UIs (not just swagger ui), so in this case also GraphQL-UI and Health-UI (if included).

If you only want to apply this style to swagger-ui (and not globally to all UIs) call the file `smallrye-open-api-ui.css` rather than `style.css`.

For more information on styling, read this blog entry: https://quarkus.io/blog/stylish-api/

### Cross Origin Resource Sharing

If you plan to consume this application from a Single Page Application running on a different domain, you will need to configure CORS (Cross-Origin Resource Sharing). Please read the CORS filter section of the "Cross-origin resource sharing" guide for more details.

## Configuration Reference

### MicroProfile OpenAPI

MicroProfile OpenAPI Core configuration is defined in MicroProfile OpenAPI Specification. More information about the MicroProfile OpenAPI annotations can be found in the MicroProfile OpenAPI API Javadoc.

### OpenAPI

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property | Type | Default
--- | --- | ---
`quarkus.smallrye-openapi.path` The path at which to register the OpenAPI Servlet. Environment variable: `QUARKUS_SMALLRYE_OPENAPI_PATH` | string | `openapi`
`quarkus.smallrye-openapi.store-schema-directory` If set, the generated OpenAPI schema documents will be stored here on build. Both openapi.json and openapi.yaml will be stored here if this is set. Environment variable: `QUARKUS_SMALLRYE_OPENAPI_STORE_SCHEMA_DIRECTORY` | path |
`quarkus.smallrye-openapi.store-schema-file-name` The name of the file in case it is being stored. Environment variable: `QUARKUS_SMALLRYE_OPENAPI_STORE_SCHEMA_FILE_NAME` | string | `openapi`
`quarkus.smallrye-openapi.always-run-filter` Do not run the filter only at startup, but every time the document is requested (dynamic). Environment variable: `QUARKUS_SMALLRYE_OPENAPI_ALWAYS_RUN_FILTER` | boolean | `false`
`quarkus.smallrye-openapi.ignore-static-document` Do not include the provided static openapi document (eg. META-INF/openapi.yaml) Environment variable: `QUARKUS_SMALLRYE_OPENAPI_IGNORE_STATIC_DOCUMENT` | boolean | `false`
`quarkus.smallrye-openapi.management.enabled` If management interface is turned on the openapi schema document will be published under the management interface. This allows you to exclude OpenAPI from management by setting the value to false Environment variable: `QUARKUS_SMALLRYE_OPENAPI_MANAGEMENT_ENABLED` | boolean | `true`
`quarkus.smallrye-openapi.additional-docs-directory` A list of local directories that should be scanned for yaml and/or json files to be included in the static model. Example: `META-INF/openapi/` Environment variable: `QUARKUS_SMALLRYE_OPENAPI_ADDITIONAL_DOCS_DIRECTORY` | list of path |
`quarkus.smallrye-openapi.security-scheme` Add a certain SecurityScheme with config Environment variable: `QUARKUS_SMALLRYE_OPENAPI_SECURITY_SCHEME` | `api-key`, `basic`, `jwt`, `oauth2`, `oidc`, `oauth2-implicit` |
`quarkus.smallrye-openapi.security-scheme-name` Add a Security Scheme name to the generated OpenAPI document Environment variable: `QUARKUS_SMALLRYE_OPENAPI_SECURITY_SCHEME_NAME` | string | `SecurityScheme`
`quarkus.smallrye-openapi.security-scheme-description` Add a description to the Security Scheme Environment variable: `QUARKUS_SMALLRYE_OPENAPI_SECURITY_SCHEME_DESCRIPTION` | string | `Authentication`
`quarkus.smallrye-openapi.security-scheme-extensions."extension-name"` Add one or more extensions to the security scheme Environment variable: `QUARKUS_SMALLRYE_OPENAPI_SECURITY_SCHEME_EXTENSIONS__EXTENSION_NAME_` | Map<String,String> |
`quarkus.smallrye-openapi.auto-add-security-requirement` This will automatically add the security requirement to all methods/classes that has a `RolesAllowed` annotation. Environment variable: `QUARKUS_SMALLRYE_OPENAPI_AUTO_ADD_SECURITY_REQUIREMENT` | boolean | `true`
`quarkus.smallrye-openapi.auto-add-tags` This will automatically add tags to operations based on the Java class name. Environment variable: `QUARKUS_SMALLRYE_OPENAPI_AUTO_ADD_TAGS` | boolean | `true`
`quarkus.smallrye-openapi.auto-add-bad-request-response` This will automatically add Bad Request (400 HTTP response) API response to operations with an input. Environment variable: `QUARKUS_SMALLRYE_OPENAPI_AUTO_ADD_BAD_REQUEST_RESPONSE` | boolean | `true`
`quarkus.smallrye-openapi.auto-add-operation-summary` This will automatically add a summary to operations based on the Java method name. Environment variable: `QUARKUS_SMALLRYE_OPENAPI_AUTO_ADD_OPERATION_SUMMARY` | boolean | `true`
`quarkus.smallrye-openapi.auto-add-server` Setting it to `true` will automatically add a default server to the schema if none is provided, using the current running server host and port. Environment variable: `QUARKUS_SMALLRYE_OPENAPI_AUTO_ADD_SERVER` | boolean |
`quarkus.smallrye-openapi.auto-add-security` This will automatically add security based on the security extension included (if any). Environment variable: `QUARKUS_SMALLRYE_OPENAPI_AUTO_ADD_SECURITY` | boolean | `true`
`quarkus.smallrye-openapi.auto-add-open-api-endpoint` This will automatically add the OpenAPI specification document endpoint to the schema. It also adds "openapi" to the list of tags and specify an "operationId" Environment variable: `QUARKUS_SMALLRYE_OPENAPI_AUTO_ADD_OPEN_API_ENDPOINT` | boolean | `false`
`quarkus.smallrye-openapi.api-key-parameter-in` Required when using `apiKey` security. The location of the API key. Valid values are "query", "header" or "cookie". Environment variable: `QUARKUS_SMALLRYE_OPENAPI_API_KEY_PARAMETER_IN` | string |
`quarkus.smallrye-openapi.api-key-parameter-name` Required when using `apiKey` security. The name of the header, query or cookie parameter to be used. Environment variable: `QUARKUS_SMALLRYE_OPENAPI_API_KEY_PARAMETER_NAME` | string |
`quarkus.smallrye-openapi.basic-security-scheme-value` Add a scheme value to the Basic HTTP Security Scheme Environment variable: `QUARKUS_SMALLRYE_OPENAPI_BASIC_SECURITY_SCHEME_VALUE` | string | `basic`
`quarkus.smallrye-openapi.jwt-security-scheme-value` Add a scheme value to the JWT Security Scheme Environment variable: `QUARKUS_SMALLRYE_OPENAPI_JWT_SECURITY_SCHEME_VALUE` | string | `bearer`
`quarkus.smallrye-openapi.jwt-bearer-format` Add a bearer format the JWT Security Scheme Environment variable: `QUARKUS_SMALLRYE_OPENAPI_JWT_BEARER_FORMAT` | string | `JWT`
`quarkus.smallrye-openapi.oauth2-security-scheme-value` Add a scheme value to the OAuth2 opaque token Security Scheme Environment variable: `QUARKUS_SMALLRYE_OPENAPI_OAUTH2_SECURITY_SCHEME_VALUE` | string | `bearer`
`quarkus.smallrye-openapi.oauth2-bearer-format` Add a scheme value to OAuth2 opaque token Security Scheme Environment variable: `QUARKUS_SMALLRYE_OPENAPI_OAUTH2_BEARER_FORMAT` | string | `Opaque`
`quarkus.smallrye-openapi.oidc-open-id-connect-url` Add a openIdConnectUrl value to the OIDC Security Scheme Environment variable: `QUARKUS_SMALLRYE_OPENAPI_OIDC_OPEN_ID_CONNECT_URL` | string |
`quarkus.smallrye-openapi.oauth2-implicit-refresh-url` Add a implicit flow refreshUrl value to the OAuth2 Security Scheme Environment variable: `QUARKUS_SMALLRYE_OPENAPI_OAUTH2_IMPLICIT_REFRESH_URL` | string |
`quarkus.smallrye-openapi.oauth2-implicit-authorization-url` Add an implicit flow authorizationUrl value to the OAuth2 Security Scheme Environment variable: `QUARKUS_SMALLRYE_OPENAPI_OAUTH2_IMPLICIT_AUTHORIZATION_URL` | string |
`quarkus.smallrye-openapi.oauth2-implicit-token-url` Add an implicit flow tokenUrl value to the OAuth2 Security Scheme Environment variable: `QUARKUS_SMALLRYE_OPENAPI_OAUTH2_IMPLICIT_TOKEN_URL` | string |
`quarkus.smallrye-openapi.open-api-version` Override the openapi version in the Schema document Environment variable: `QUARKUS_SMALLRYE_OPENAPI_OPEN_API_VERSION` | string |
`quarkus.smallrye-openapi.info-title` Set the title in Info tag in the Schema document Environment variable: `QUARKUS_SMALLRYE_OPENAPI_INFO_TITLE` | string |
`quarkus.smallrye-openapi.info-version` Set the version in Info tag in the Schema document Environment variable: `QUARKUS_SMALLRYE_OPENAPI_INFO_VERSION` | string |
`quarkus.smallrye-openapi.info-description` Set the description in Info tag in the Schema document Environment variable: `QUARKUS_SMALLRYE_OPENAPI_INFO_DESCRIPTION` | string |
`quarkus.smallrye-openapi.info-terms-of-service` Set the terms of the service in Info tag in the Schema document Environment variable: `QUARKUS_SMALLRYE_OPENAPI_INFO_TERMS_OF_SERVICE` | string |
`quarkus.smallrye-openapi.info-contact-email` Set the contact email in Info tag in the Schema document Environment variable: `QUARKUS_SMALLRYE_OPENAPI_INFO_CONTACT_EMAIL` | string |
`quarkus.smallrye-openapi.info-contact-name` Set the contact name in Info tag in the Schema document Environment variable: `QUARKUS_SMALLRYE_OPENAPI_INFO_CONTACT_NAME` | string |
`quarkus.smallrye-openapi.info-contact-url` Set the contact url in Info tag in the Schema document Environment variable: `QUARKUS_SMALLRYE_OPENAPI_INFO_CONTACT_URL` | string |
`quarkus.smallrye-openapi.info-license-name` Set the license name in Info tag in the Schema document Environment variable: `QUARKUS_SMALLRYE_OPENAPI_INFO_LICENSE_NAME` | string |
`quarkus.smallrye-openapi.info-license-url` Set the license url in Info tag in the Schema document Environment variable: `QUARKUS_SMALLRYE_OPENAPI_INFO_LICENSE_URL` | string |
`quarkus.smallrye-openapi.operation-id-strategy` Set the strategy to automatically create an operation Id Environment variable: `QUARKUS_SMALLRYE_OPENAPI_OPERATION_ID_STRATEGY` | `method`, `class-method`, `package-class-method` |
`quarkus.smallrye-openapi.merge-schema-examples` Set this boolean value to enable or disable the merging of the deprecated `@Schema` `example` property into the `examples` array introduced in OAS 3.1.0. If set to `false`, the deprecated `example` will be kept as a separate annotation on the schema in the OpenAPI model. Environment variable: `QUARKUS_SMALLRYE_OPENAPI_MERGE_SCHEMA_EXAMPLES` | boolean | `true`
`quarkus.smallrye-openapi.enabled` Enable the openapi endpoint. By default it’s enabled. Environment variable: `QUARKUS_SMALLRYE_OPENAPI_ENABLED` | boolean | `true`
`quarkus.smallrye-openapi.servers` Specify the list of global servers that provide connectivity information Environment variable: `QUARKUS_SMALLRYE_OPENAPI_SERVERS` | list of string |

### Swagger UI

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property | Type | Default
--- | --- | ---
`quarkus.swagger-ui.path` The path where Swagger UI is available. The value `/` is not allowed as it blocks the application from serving anything else. By default, this value will be resolved as a path relative to `${quarkus.http.non-application-root-path}`. Environment variable: `QUARKUS_SWAGGER_UI_PATH` | string | `swagger-ui`
`quarkus.swagger-ui.always-include` If this should be included every time. By default, this is only included when the application is running in dev mode. Environment variable: `QUARKUS_SWAGGER_UI_ALWAYS_INCLUDE` | boolean | `false`
`quarkus.swagger-ui.urls."name"` The urls that will be included as options. By default, the OpenAPI path will be used. Here you can override that and supply multiple urls that will appear in the TopBar plugin. Environment variable: `QUARKUS_SWAGGER_UI_URLS__NAME_` | Map<String,String> |
`quarkus.swagger-ui.urls-primary-name` If urls option is used, this will be the name of the default selection. Environment variable: `QUARKUS_SWAGGER_UI_URLS_PRIMARY_NAME` | string |
`quarkus.swagger-ui.title` The html title for the page. Environment variable: `QUARKUS_SWAGGER_UI_TITLE` | string |
`quarkus.swagger-ui.theme` Swagger UI theme to be used. Environment variable: `QUARKUS_SWAGGER_UI_THEME` | `original`, `feeling-blue`, `flattop`, `material`, `monokai`, `muted`, `newspaper`, `outline` |
`quarkus.swagger-ui.footer` A footer for the html page. Nothing by default. Environment variable: `QUARKUS_SWAGGER_UI_FOOTER` | string |
`quarkus.swagger-ui.deep-linking` If set to true, enables deep linking for tags and operations. Environment variable: `QUARKUS_SWAGGER_UI_DEEP_LINKING` | boolean |
`quarkus.swagger-ui.display-operation-id` Controls the display of operationId in operations list. The default is false. Environment variable: `QUARKUS_SWAGGER_UI_DISPLAY_OPERATION_ID` | boolean |
`quarkus.swagger-ui.default-models-expand-depth` The default expansion depth for models (set to -1 completely hide the models). Environment variable: `QUARKUS_SWAGGER_UI_DEFAULT_MODELS_EXPAND_DEPTH` | int |
`quarkus.swagger-ui.default-model-expand-depth` The default expansion depth for the model on the model-example section. Environment variable: `QUARKUS_SWAGGER_UI_DEFAULT_MODEL_EXPAND_DEPTH` | int |
`quarkus.swagger-ui.default-model-rendering` Controls how the model is shown when the API is first rendered. Environment variable: `QUARKUS_SWAGGER_UI_DEFAULT_MODEL_RENDERING` | string |
`quarkus.swagger-ui.display-request-duration` Controls the display of the request duration (in milliseconds) for "Try it out" requests. Environment variable: `QUARKUS_SWAGGER_UI_DISPLAY_REQUEST_DURATION` | boolean |
`quarkus.swagger-ui.doc-expansion` Controls the default expansion setting for the operations and tags. Environment variable: `QUARKUS_SWAGGER_UI_DOC_EXPANSION` | `list`, `full`, `none` |
`quarkus.swagger-ui.filter` 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. Environment variable: `QUARKUS_SWAGGER_UI_FILTER` | string |
`quarkus.swagger-ui.max-displayed-tags` If set, limits the number of tagged operations displayed to at most this many. The default is to show all operations. Environment variable: `QUARKUS_SWAGGER_UI_MAX_DISPLAYED_TAGS` | int |
`quarkus.swagger-ui.operations-sorter` 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. Environment variable: `QUARKUS_SWAGGER_UI_OPERATIONS_SORTER` | string |
`quarkus.swagger-ui.show-extensions` Controls the display of vendor extension (x-) fields and values for Operations, Parameters, and Schema. Environment variable: `QUARKUS_SWAGGER_UI_SHOW_EXTENSIONS` | boolean |
`quarkus.swagger-ui.show-common-extensions` Controls the display of extensions (pattern, maxLength, minLength, maximum, minimum) fields and values for Parameters. Environment variable: `QUARKUS_SWAGGER_UI_SHOW_COMMON_EXTENSIONS` | boolean |
`quarkus.swagger-ui.tags-sorter` 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. Environment variable: `QUARKUS_SWAGGER_UI_TAGS_SORTER` | string |
`quarkus.swagger-ui.on-complete` Provides a mechanism to be notified when Swagger UI has finished rendering a newly provided definition. Environment variable: `QUARKUS_SWAGGER_UI_ON_COMPLETE` | string |
`quarkus.swagger-ui.syntax-highlight` Set to `false` to deactivate syntax highlighting of payloads and cURL command. Can be otherwise an object with the `activate` and `theme` properties. Environment variable: `QUARKUS_SWAGGER_UI_SYNTAX_HIGHLIGHT` | string |
`quarkus.swagger-ui.oauth2-redirect-url` OAuth redirect URL. Environment variable: `QUARKUS_SWAGGER_UI_OAUTH2_REDIRECT_URL` | string |
`quarkus.swagger-ui.request-interceptor` MUST be a function. Function to intercept remote definition, "Try it out", and OAuth 2.0 requests. Accepts one argument requestInterceptor(request) and must return the modified request, or a Promise that resolves to the modified request. Environment variable: `QUARKUS_SWAGGER_UI_REQUEST_INTERCEPTOR` | string |
`quarkus.swagger-ui.request-curl-options` If set, MUST be an array of command line options available to the curl command. This can be set on the mutated request in the requestInterceptor function. Environment variable: `QUARKUS_SWAGGER_UI_REQUEST_CURL_OPTIONS` | list of string |
`quarkus.swagger-ui.response-interceptor` MUST be a function. Function to intercept remote definition, "Try it out", and OAuth 2.0 responses. Accepts one argument responseInterceptor(response) and must return the modified response, or a Promise that resolves to the modified response. Environment variable: `QUARKUS_SWAGGER_UI_RESPONSE_INTERCEPTOR` | string |
`quarkus.swagger-ui.show-mutated-request` If set to true, uses the mutated request returned from a requestInterceptor to produce the curl command in the UI, otherwise the request before the requestInterceptor was applied is used. Environment variable: `QUARKUS_SWAGGER_UI_SHOW_MUTATED_REQUEST` | boolean |
`quarkus.swagger-ui.supported-submit-methods` 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. Environment variable: `QUARKUS_SWAGGER_UI_SUPPORTED_SUBMIT_METHODS` | list of `get`, `put`, `post`, `delete`, `options`, `head`, `patch`, `trace` |
`quarkus.swagger-ui.validator-url` By default, Swagger UI attempts to validate specs against swagger.io’s online validator. You can use this parameter to set a different validator URL, for example for locally deployed validators (Validator Badge). Setting it to either none, 127.0.0.1 or localhost will disable validation. Environment variable: `QUARKUS_SWAGGER_UI_VALIDATOR_URL` | string |
`quarkus.swagger-ui.with-credentials` If set to true, enables passing credentials, as defined in the Fetch standard, in CORS requests that are sent by the browser. Environment variable: `QUARKUS_SWAGGER_UI_WITH_CREDENTIALS` | boolean |
`quarkus.swagger-ui.model-property-macro` Function to set default values to each property in model. Accepts one argument modelPropertyMacro(property), property is immutable Environment variable: `QUARKUS_SWAGGER_UI_MODEL_PROPERTY_MACRO` | string |
`quarkus.swagger-ui.parameter-macro` Function to set default value to parameters. Accepts two arguments parameterMacro(operation, parameter). Operation and parameter are objects passed for context, both remain immutable Environment variable: `QUARKUS_SWAGGER_UI_PARAMETER_MACRO` | string |
`quarkus.swagger-ui.persist-authorization` If set to true, it persists authorization data and it would not be lost on browser close/refresh Environment variable: `QUARKUS_SWAGGER_UI_PERSIST_AUTHORIZATION` | boolean |
`quarkus.swagger-ui.layout` The name of a component available via the plugin system to use as the top-level layout for Swagger UI. Environment variable: `QUARKUS_SWAGGER_UI_LAYOUT` | string |
`quarkus.swagger-ui.plugins` A list of plugin functions to use in Swagger UI. Environment variable: `QUARKUS_SWAGGER_UI_PLUGINS` | list of string |
`quarkus.swagger-ui.scripts` A list of external scripts (usually plugins) to use in Swagger UI. Environment variable: `QUARKUS_SWAGGER_UI_SCRIPTS` | list of string |
`quarkus.swagger-ui.presets` A list of presets to use in Swagger UI. Environment variable: `QUARKUS_SWAGGER_UI_PRESETS` | list of string |
`quarkus.swagger-ui.oauth-client-id` OAuth default clientId - Used in the initOAuth method. Environment variable: `QUARKUS_SWAGGER_UI_OAUTH_CLIENT_ID` | string |
`quarkus.swagger-ui.oauth-client-secret` OAuth default clientSecret - Used in the initOAuth method. Environment variable: `QUARKUS_SWAGGER_UI_OAUTH_CLIENT_SECRET` | string |
`quarkus.swagger-ui.oauth-realm` OAuth1 Realm query parameter added to authorizationUrl and tokenUrl - Used in the initOAuth method. Environment variable: `QUARKUS_SWAGGER_UI_OAUTH_REALM` | string |
`quarkus.swagger-ui.oauth-app-name` OAuth application name, displayed in authorization popup - Used in the initOAuth method. Environment variable: `QUARKUS_SWAGGER_UI_OAUTH_APP_NAME` | string |
`quarkus.swagger-ui.oauth-scope-separator` OAuth scope separator for passing scopes - Used in the initOAuth method. Environment variable: `QUARKUS_SWAGGER_UI_OAUTH_SCOPE_SEPARATOR` | string |
`quarkus.swagger-ui.oauth-scopes` OAuth Scopes, separated using the oauthScopeSeparator - Used in the initOAuth method. Environment variable: `QUARKUS_SWAGGER_UI_OAUTH_SCOPES` | string |
`quarkus.swagger-ui.oauth-additional-query-string-params` OAuth additional query parameters added to authorizationUrl and tokenUrl - Used in the initOAuth method. Environment variable: `QUARKUS_SWAGGER_UI_OAUTH_ADDITIONAL_QUERY_STRING_PARAMS` | string |
`quarkus.swagger-ui.oauth-use-basic-authentication-with-access-code-grant` OAuth only activated for the accessCode flow. During the authorization_code request to the tokenUrl, pass the Client Password using the HTTP Basic Authentication scheme - Used in the initOAuth method. Environment variable: `QUARKUS_SWAGGER_UI_OAUTH_USE_BASIC_AUTHENTICATION_WITH_ACCESS_CODE_GRANT` | boolean |
`quarkus.swagger-ui.oauth-use-pkce-with-authorization-code-grant` OAuth only applies to authorization code flows. Proof Key for Code Exchange brings enhanced security for OAuth public clients - Used in the initOAuth method. Environment variable: `QUARKUS_SWAGGER_UI_OAUTH_USE_PKCE_WITH_AUTHORIZATION_CODE_GRANT` | boolean |
`quarkus.swagger-ui.preauthorize-basic-auth-definition-key` Pre-authorize Basic Auth, programmatically set DefinitionKey for a Basic authorization scheme - Used in the preauthorizeBasic method. Environment variable: `QUARKUS_SWAGGER_UI_PREAUTHORIZE_BASIC_AUTH_DEFINITION_KEY` | string |
`quarkus.swagger-ui.preauthorize-basic-username` Pre-authorize Basic Auth, programmatically set Username for a Basic authorization scheme - Used in the preauthorizeBasic method. Environment variable: `QUARKUS_SWAGGER_UI_PREAUTHORIZE_BASIC_USERNAME` | string |
`quarkus.swagger-ui.preauthorize-basic-password` Pre-authorize Basic Auth, programmatically set Password for a Basic authorization scheme - Used in the preauthorizeBasic method. Environment variable: `QUARKUS_SWAGGER_UI_PREAUTHORIZE_BASIC_PASSWORD` | string |
`quarkus.swagger-ui.preauthorize-api-key-auth-definition-key` Pre-authorize ApiKey Auth, programmatically set DefinitionKey for an API key or Bearer authorization scheme - Used in the preauthorizeApiKey method. Environment variable: `QUARKUS_SWAGGER_UI_PREAUTHORIZE_API_KEY_AUTH_DEFINITION_KEY` | string |
`quarkus.swagger-ui.preauthorize-api-key-api-key-value` Pre-authorize ApiKey Auth, programmatically set ApiKeyValue for an API key or Bearer authorization scheme - Used in the preauthorizeApiKey method. Environment variable: `QUARKUS_SWAGGER_UI_PREAUTHORIZE_API_KEY_API_KEY_VALUE` | string |
`quarkus.swagger-ui.query-config-enabled` If set to true, this allows the user to modify and test different query parameters in the API request Environment variable: `QUARKUS_SWAGGER_UI_QUERY_CONFIG_ENABLED` | boolean | `false`
`quarkus.swagger-ui.try-it-out-enabled` If try it out should be enabled by default Environment variable: `QUARKUS_SWAGGER_UI_TRY_IT_OUT_ENABLED` | boolean | `false`
`quarkus.swagger-ui.enabled` If Swagger UI is included, it should be enabled/disabled. By default, Swagger UI is enabled if it is included (see `always-include`). Environment variable: `QUARKUS_SWAGGER_UI_ENABLED` | boolean | `true`