Spring Boot

Install

Add the dependency to pom.xml:

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.3.0</version>
</dependency>

Or for Gradle (build.gradle.kts):

implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0")

Default endpoint

No additional configuration is needed. Spring Boot exposes the spec at:

http://localhost:8080/v3/api-docs

And the Swagger UI at /swagger-ui.html.

Expose at /openapi.json

Add to application.properties:

springdoc.api-docs.path=/openapi.json

Or application.yml:

springdoc:
  api-docs:
    path: /openapi.json

Customize metadata

// OpenApiConfig.java
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {
  @Bean
  public OpenAPI customOpenAPI() {
    return new OpenAPI()
      .info(new Info()
        .title("My API")
        .version("1.0.0")
        .description("API description"));
  }
}

Add descriptions to endpoints

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;

@RestController
@Tag(name = "items")
public class ItemController {

  @GetMapping("/items/{id}")
  @Operation(operationId = "getItem", summary = "Get a single item")
  public Item getItem(@PathVariable Long id) {
    return new Item(id, "Widget");
  }
}

Make it publicly accessible

Deploy your app or use a tunnel for local testing:

ngrok http 8080
# then use: https://<random>.ngrok.io/openapi.json

Verify

Visit /openapi.json in your browser. You should see a valid OpenAPI 3.x JSON document.

Paste this URL into Automiel’s import step.