Adding OpenAPI Specifications to Spring Boot RESTful APIs

The OpenAPI Specification (OAS) defines

a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic“.

This post demonstrates how to add OpenAPI specifications (version 3.0.1) to document existing RESTful APIs in a Spring Boot/Spring MVC project. This would be useful when you have an existing application and want to expose its APIs via OpenAPI. I will walk through how to setup the project and update the codes to generate the desired documentation.

Project Setup

I use the springdoc-openapi library to generate the OpenAPI documentation. Setting this up is straight forward, just add the following dependencies in your Maven pom file.


Once the above is included, the OpenAPI documentation will be generated for all RESTful APIs in the application and made available at the path /v3/api-docs. For example


The above URL generates the OpenAPI document in json. For yaml format, use the following URL


The above Maven also includes Swagger UI which can be accessed via the URL



Springdoc OpenAPI Configuration

Now we have added the springdoc library, we can start customize our API codes to generate the OpenAPI documentation.

General API Info & Servers

General information about the APIs and server URLs are configured under the @OpenAPIDefinition annotation. This is used to provide general metadata information about the APIs such as version, contact and licencing.

     info = @Info(
               title = "Order API",
               version = "v2",
	       description = "This app provides REST APIs for order entities",
	       contact = @Contact(
				name = "Raymond",
				email = "",
				url = ""
     servers = {
               url="<dev url>",
               description="DEV Server"
               url="<prod url>",
               description="PROD Server"
public class OpenApiConfig {

The corresponding OpenAPI document for the above annotation is shown below

openapi: 3.0.1
  title: Order API
  description: This app provides REST APIs for order entities
    name: Raymond
  version: v2
- url: <dev url>
  description: DEV Server
  variables: {}
- url: <prod url>
  description: PROD Server
  variables: {}


There are two steps for defining API security in OpenAPI.

First, define a global security schema. For example, an OAuth2 schema using JWT can be defined using the @SecurityScheme annotation below:

     name = "myOauth2Security",
     type = SecuritySchemeType.OAUTH2,
     in = SecuritySchemeIn.HEADER,
     bearerFormat = "jwt",
     flows = @OAuthFlows(
               implicit = @OAuthFlow(
                  authorizationUrl = "",
                  scopes = {
                     @OAuthScope(name = "read", description = "read access"),
                     @OAuthScope(name = "write", description = "Write access")

Now that a global security schema has been defined, we can apply it to any API by annotating the method in the REST controller with @Operation annotation and specify the security with @SecurityRequirement annotation by referring to the schema above by its name.

public class OrderController {
          security = @SecurityRequirement(name = "myOauth2Security", scopes = "write"),
          // ... other attributes 
     @PostMapping(value = "/order", consumes = MediaType.APPLICATION_JSON_VALUE)
     public void postOrder(OrderDto order) {
          // Implementation codes

Paths & Operations

Springdoc is smart enough to interpret the path of an endpoint from its Spring MVC request mapping annotation, i.e. @PostMapping, @GetMapping etc.

To provide more information about an endpoint, use @Operation annotation as shown in the previous section. Below is a complete example for an endpoint to post a new order to the backend server:

public class OrderController {
          summary = "Create a new order",
          description = "Use this endpoint to create a new order in the backend",
          security = @SecurityRequirement(name = "myOauth2Security", scopes = "write"),
          responses= {
              @ApiResponse(responseCode = "201", description = "Success"),
              @ApiResponse(responseCode = "403", description = "Forbidden"),
              @ApiResponse(responseCode = "500", description = "Server Error")
     @ResponseStatus(code = HttpStatus.CREATED)
     @PostMapping(value = "/order", consumes = MediaType.APPLICATION_JSON_VALUE)
     public void postOrder(OrderDto order) {
           // Implementation codes

Note we provide here a brief summary and description of the endpoint. Also, a number of possible responses and their reasons are included using the @ApiResponse annotation in the responses attribute. The above annotation will result in the following OpenAPI fragment

      summary: Create a new order
      description: Use this endpoint to create a new order in the backend
      operationId: postOrder
              $ref: '#/components/schemas/OrderDto'
          description: Success
          description: Forbidden
          description: Server Error
      - myOauth2Security:
        - write


The above API expects an OrderDto object in the request. Springdoc will automatically generate the component element of the object in OpenAPI. It will include all the object properties and their data types. To add more description of the object, we can use the @Schema annotation.

     name = "orderDto",
     description = "Data object for an order",
     oneOf = OrderDto.class
public class OrderDto {

Springdoc also supports JSR-303. For example

public class OrderDto {
     private Long id;
     private String orderName;
     private String customerName;
     private String customerAddress;
     private BigDecimal orderAmount;
     private List<OrderLineDto> lines;

The above will generate the following OpenAPI fragment

      - customerAddress
      - customerName
      - lines
      - orderName
      type: object
      description: Data object for an order
          type: integer
          format: int64
          type: string
          type: string
          type: string
          type: number
          type: array
            $ref: '#/components/schemas/OrderLineDto'

Note the required fields, marked by @NotNull, are defined in the required: elements.


This post has demonstrated how to update a Spring Boot / MVC project to automatically generate OpenAPI specification for the application’s API endpoints. The OpenAPI document can be used by human and computer, for example to generate client codes to consume the API using tools such as the OpenAPI Generator.

For more detailed information about OpenAPI, refer to specification here. The Swagger site also has a section which explains in details the basic structure of an OpenAPI document as well as its individual elements.