SpringBoot uses Swagger to generate multi-module API documentation

In large projects, multi-module architecture design is usually adopted to improve the maintainability and scalability of the code. When using Swagger to generate API documents for multi-module projects, some special configuration is required. The following is a Spring Boot multi-module project as an example to introduce in detail how to use Swagger to generate multi-module API documentation.

Project structure

Suppose we have a Spring Boot project with multiple modules, the structure is as follows:

multi-module-project
├── common-module
│   └── src
│       └── main
│           └── java
│               └── com
│                   └── example
│                       └── common
│                           └── ...
├── module-a
│   └── src
│       └── main
│           └── java
│               └── com
│                   └── example
│                       └── modulea
│                           └── ...
├── module-b
│   └── src
│       └── main
│           └── java
│               └── com
│                   └── example
│                       └── moduleb
│                           └── ...
└── api-gateway
    └── src
        └── main
            └── java
                └── com
                    └── example
                        └── apigateway
                            └── ...

Step 1: Add dependencies

Add Swagger-related dependencies to each module that needs to generate the API document:

<dependencies>
    <!-- Swagger API annotation -->
    <dependency>
        <groupId></groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <!-- Swagger UI -->
    <dependency>
        <groupId></groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
</dependencies>

Step 2: Configure Swagger

Create a Swagger configuration class in each module, for example in module-a:

package ;
 
import ;
import ;
import ;
import ;
import ;
import ;
import ..EnableSwagger2;
 
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
               .select()
               .apis((""))
               .paths(())
               .build();
    }
}

Similar configuration is done in module-b, just replace basePackage with .

Step 3: Unified API Gateway Configuration (optional)

If you have an API gateway module (such as api-gateway) in your project, you can configure Swagger in that module to aggregate the API documents of each module.

package ;
 
import ;
import ;
import ;
import ;
import ;
import ;
import ..EnableSwagger2;
 
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
               .select()
               .apis((""))
               .paths(())
               .build();
    }
}

The basePackage here is set to the root package containing all module controllers, so Swagger will scan the controllers of all modules under the package and generate a unified API document.

Step 4: Add API annotations

Add Swagger annotations on the controller classes and methods of each module to describe API information. For example in the controller of module-a:

package ;
 
import ;
import ;
import ;
import ;
import ;
 
@RestController
@RequestMapping("/module-a")
@Api(value = "Module A API", description = "This is Module A's API documentation")
public class ModuleAController {
    @GetMapping("/hello")
    @ApiOperation(value = "Get Module A's greeting", notes = "Return to a simple greeting")
    public String hello() {
        return "Hello from Module A!";
    }
}

Similar operations are performed in the controller of module-b.

Step 5: View API Documentation

Start the Spring Boot application of each module, access the Swagger UI address of the corresponding module (such as http://localhost:8080/module-a/ or http://localhost:8080/api-gateway/, the port number and path are modified according to the actual situation), and you can view each module or unified API documentation.

Things to note

Make sure that the basePackage in the Swagger configuration class for each module is configured correctly to ensure that the controllers of the corresponding module can be scanned.

If you use API gateway for document aggregation, pay attention to the gateway routing configuration to ensure that the API of each module can be accessed correctly.

Swagger configuration can be customized as needed, such as setting document title, description, version and other information.

Through the above steps, you can use Swagger to generate clear and unified API documents for Spring Boot multi-module projects, which are easy for developers and testers to view and use.

This is the article about SpringBoot using Swagger to generate multi-module API documents. For more information about SpringBoot Swagger to generate API documents, please search for my previous articles or continue browsing the related articles below. I hope everyone will support me in the future!