Can Springdoc Read and Combine Configs from Autoscan and File?

Springdoc is a popular library for generating machine and human-readable specifications for REST APIs in a Spring Boot application. It allows you to automatically generate OpenAPI and Swagger UI for your application. One of the most useful features of Springdoc is the ability to read and combine configurations from autoscan and file.

By default, Springdoc automatically scans your application for Spring components and generates the OpenAPI specification based on the annotations found in the code. However, you can also provide a separate OpenAPI specification file to customize or extend the generated specification. In this article, we will show you how to read and combine configurations from autoscan and file in Springdoc.

Reading Configurations from Autoscan

Springdoc automatically scans your application for Spring components annotated with @RestController, @Controller, @Service, and @Repository annotations. It then generates the OpenAPI specification based on the annotations found in the code. You don't need to do anything to enable autoscan; it is enabled by default when you add Springdoc to your application.

Here's an example of a simple Spring component that can be autodetected by Springdoc:

@RestController
public class ExampleController {

    @GetMapping("/example")
    public String getExample() {
        return "Hello, World!";
    }
}

When you run your application, Springdoc will automatically generate an OpenAPI specification for this component. You can view the generated specification by navigating to the /v3/api-docs endpoint in your browser or by using a tool like Swagger UI.

Reading Configurations from File

If you want to customize or extend the OpenAPI specification generated by Springdoc, you can provide a separate OpenAPI specification file. The file should be written in the OpenAPI specification format and should be placed in the src/main/resources/static directory of your application.

Here's an example of an OpenAPI specification file:

openapi: 3.0.3
info:
  title: My API
  description: My API description
  version: 1.0.0
servers:
  - url: http://localhost:8080/api
paths: {}
components: {}

When you run your application, Springdoc will automatically combine the OpenAPI specification generated from autoscan with the OpenAPI specification provided in the file. You can view the combined specification by navigating to the /v3/api-docs endpoint in your browser or by using a tool like Swagger UI.

Combining Configurations from Autoscan and File

When you provide both an OpenAPI specification file and Spring components annotated with the @RestController, @Controller, @Service, and @Repository annotations, Springdoc will automatically combine the configurations from both sources. The resulting OpenAPI specification will include the information from both sources.

Here's an example of combining configurations from autoscan and file:

First, let's create a simple Spring component:

@RestController
public class ExampleController {

    @GetMapping("/example")
    public String getExample() {
        return "Hello, World!";
    }
}

Next, let's create an OpenAPI specification file:

openapi: 3.0.3
info:
  title: My API
  description: My API description
  version: 1.0.0
servers:
  - url: http://localhost:8080/api
paths:
  /example:
    get:
      summary: Get Example
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Hello, World!

When you run your application, Springdoc will automatically combine the configurations from both sources. You can view the combined specification by navigating to the /v3/api-docs endpoint in your browser or by using a tool like Swagger UI.

In this article, we have shown you how to read and combine configurations from autoscan and file in Springdoc. By default, Springdoc automatically scans your application for Spring components and generates the OpenAPI specification based on the annotations found in the code. However, you can also provide a separate OpenAPI specification file to customize or extend the generated specification. When you provide both an OpenAPI specification file and Spring components annotated with the @RestController, @Controller, @Service, and @Repository annotations, Springdoc will automatically combine the configurations from both sources.

References