Java微服务开发之Swagger详解

本攻略将详细讲解Java微服务开发中的Swagger，包括搭建过程、使用方法、示例说明。

搭建过程

1. 创建一个Spring Boot项目

1. 创建一个Spring Boot项目，命名example。

2. 在pom.xml文件中添加以下依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

其中，springfox-swagger2表示Swagger的核心库，springfox-swagger-ui表示Swagger的UI库。

2. 创建Swagger配置类

1. 创建Swagger配置类，命名为SwaggerConfig，添加以下代码：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

其中，@Configuration注解用于指定配置类，@EnableSwagger2注解用于启用Swagger，@Bean注解用于指定Docket对象，RequestHandlerSelectors.basePackage用于指定扫描的包，PathSelectors.any()用于指定扫描的路径。

3. 验证Swagger

1. 启动服务，执行以下命令：

mvn spring-boot:run

1. 访问Swagger UI，执行以下命令：

http://localhost:8080/swagger-ui.html

1. 可以看到Swagger UI成功展示了API文档。

使用方法

1. 添加API文档注解

1. 在Controller类中添加API文档注解，例如：

@RestController
@Api(tags = "用户管理")
public class UserController {
    @GetMapping("/users")
    @ApiOperation(value = "获取用户列表", notes = "获取所有用户的列表")
    public List<User> getUsers() {
        // ...
    }

    @PostMapping("/users")
    @ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
    public void createUser(@RequestBody User user) {
        // ...
    }
}

其中，@Api注解用于指定API文档的标签，@ApiOperation注解用于指定API文档的描述。

2. 验证API文档

1. 启动服务，执行以下命令：

mvn spring-boot:run

1. 访问Swagger UI，执行以下命令：

http://localhost:8080/swagger-ui.html

1. 可以看到Swagger UI成功展示了API文档，并包含了UserController中的API。

示例说明

以下是两个示例说明，分别演示了如何使用Swagger。

示例一：使用Swagger UI查看API文档

1. 创建一个Spring Boot项目，命名为example-swagger-ui。

2. 在pom.xml文件中添加以下依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

1. 创建一个UserController，添加以下代码：

@RestController
@Api(tags = "用户管理")
public class UserController {
    @GetMapping("/users")
    @ApiOperation(value = "获取用户列表", notes = "获取所有用户的列表")
    public List<User> getUsers() {
        // ...
    }

    @PostMapping("/users")
    @ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
    public void createUser(@RequestBody User user) {
        // ...
    }
}

其中，@Api注解用于指定API文档的标签，@ApiOperation注解用于指定API文档的描述。

1. 创建一个Swagger配置类，添加以下代码：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

其中，@Configuration注解用于指定配置类，@EnableSwagger2注解用于启用Swagger，@Bean注解用于指定Docket对象，RequestHandlerSelectors.basePackage用于指定扫描的包，PathSelectors.any()用于指定扫描的路径。

1. 启动服务，执行以下命令：

mvn spring-boot:run

1. 访问Swagger UI，执行以下命令：

http://localhost:8080/swagger-ui.html

1. 可以看到Swagger UI成功展示了API文档，并包含了UserController中的API。

示例二：使用Swagger生成API文档

1. 创建一个Spring Boot项目，命名为example-swagger-gen。

2. 在pom.xml文件中添加以下依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

1. 创建一个UserController，添加以下代码：

@RestController
@Api(tags = "用户管理")
public class UserController {
    @GetMapping("/users")
    @ApiOperation(value = "获取用户列表", notes = "获取所有用户的列表")
    public List<User> getUsers() {
        // ...
    }

    @PostMapping("/users")
    @ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
    public void createUser(@RequestBody User user) {
        // ...
    }
}

其中，@Api注解用于指定API文档的标签，@ApiOperation注解用于指定API文档的描述。

1. 启动服务，执行以下命令：

mvn spring-boot:run

1. 访问API文档，执行以下命令：

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

1. 可以看到API文档成功生成，并包含了UserController中的API。

总结

使用Java Swagger可以方便地生成API文档，提高开发效率和代码可读性。在实际应用中，我们可以根据具体情况选择合适的Swagger版本和配置方式，满足业务需求和技术发展。使用Swagger UI查看API文档可以方便地了解API的使用方法和参数，使用Swagger生成API文档可以方便地与其他系统进行集成。