Careeroza

springdoc-openapi Setup

OpenAPI and Swagger UI

OpenAPI is a standard JSON/YAML description of a REST API: paths, parameters, request and response schemas. Swagger UI turns it into a web page where you can read and try every endpoint. springdoc-openapi generates both from your controllers automatically.

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.8.6</version>   <!-- 2.8.x for Spring Boot 3.4/3.5; use 2.6.x for Boot 3.3 -->
</dependency>

Open the Docs

Example

Start the app and open the URLs:

http://localhost:8080/swagger-ui.html      # interactive UI (redirects to /swagger-ui/index.html)
http://localhost:8080/v3/api-docs          # raw OpenAPI JSON
http://localhost:8080/v3/api-docs.yaml     # same, as YAML

Example

curl -s localhost:8080/v3/api-docs | head -c 400

Example output

{"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"http://localhost:8080","description":"Generated server url"}],"paths":{"/api/products/{id}":{"get":{"tags":["product-controller"],"operationId":"get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],...

Note: Bean Validation annotations show up in the schema automatically: @NotBlank becomes required, @Size(max = 120) becomes maxLength: 120.

API Info and Settings

@Configuration
class OpenApiConfig {
    @Bean
    OpenAPI shopEaseOpenApi() {
        return new OpenAPI().info(new Info()
                .title("ShopEase API")
                .version("v1")
                .description("Products, cart and orders for the ShopEase store")
                .contact(new Contact().name("ShopEase Backend Team").email("[email protected]")));
    }
}

Example

application.yml

springdoc:
  swagger-ui:
    path: /docs                # UI at /docs
    operations-sorter: method
  api-docs:
    path: /v3/api-docs
  packages-to-scan: com.shopease