Swagger教程详解

一、Swagger是什么？

Swagger是一个面向RESTful API的开源软件框架。它提供了一组工具，可以帮助您描述、生成、消费API。通过使用Swagger，您可以更好地了解API的工作方式以及如何使用它。

Spring Boot集成Swagger，可以让我们在开发API文档时，少写很多样板代码，Swagger生成器会根据注解自动生成API文档，并且生成的API文档非常详细，展示了API的参数、请求方式、响应格式等等。

二、快速上手Swagger

1、首先，在pom.xml中引入Swagger的依赖。

<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>

2、创建Swagger2配置类，配置Swagger基本信息

package com.example.swaggerdemo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SwaggerDemo API")
                .description("SwaggerDemo后台API接口文档")
                .termsOfServiceUrl("http://127.0.0.1:8080/")
                .version("1.0")
                .build();
    }
}

3、在Controller层的方法上使用Swagger注解，用于API的说明、请求参数的说明等。

@Api(tags = "用户管理")
@RestController
@RequestMapping("/user")
public class UserController {

    @Autowired
    private UserRepository userRepository;

    @ApiOperation(value = "获取用户列表")
    @GetMapping("/")
    public List<User> getUserList() {
        return userRepository.findAll();
    }

    @ApiOperation(value = "新增用户")
    @PostMapping("/")
    public User addUser(@ApiParam(value = "用户对象", required = true) @RequestBody User user) {
        return userRepository.save(user);
    }

    @ApiOperation(value = "根据ID查询用户")
    @GetMapping("/{id}")
    public User getUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) {
        return userRepository.findById(id).orElse(null);
    }

    @ApiOperation(value = "根据ID更新用户信息")
    @PutMapping("/{id}")
    public User updateUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id,
                               @ApiParam(value = "用户对象", required = true) @RequestBody User user) {
        user.setId(id);
        return userRepository.save(user);
    }

    @ApiOperation(value = "根据ID删除用户")
    @DeleteMapping("/{id}")
    public void deleteUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) {
        userRepository.deleteById(id);
    }
}

三、Swagger的常用注解

Swagger常用注解有@Api、@ApiOperation、@ApiParam、@ApiModel、@ApiModelProperty这些注解。

1、@Api：标记一个Controller类为Swagger资源。

2、@ApiOperation：标记Controller方法为Swagger操作。

3、@ApiParam：标记方法参数的名称和描述。

4、@ApiModel和@ApiModelProperty：用于Swagger Model类的Javadoc。其中，@ApiModel描述模型的名称和说明，@ApiModelProperty描述模型属性的名称、描述信息、是否必须等。

四、Swagger的高级用法

1、全局配置

通过SwaggerConfig的apiInfo()方法，可以设置所有Controller的通用信息。

private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("SwaggerDemo API")
            .description("SwaggerDemo后台API接口文档")
            .termsOfServiceUrl("http://127.0.0.1:8080/")
            .version("1.0")
            .contact(new Contact("SwaggerDemo", "", "xxx@qq.com")) //设置API创建人信息
            .license("Apache License 2.0")
            .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
            .build();
}

2、局部配置

可以在方法级别上对Swagger进行局部配置，例如针对某个方法不展示。

@ApiOperation(value = "获取用户列表")
@ApiResponses(value = {
    @ApiResponse(code = 401, message = "未授权"),
    @ApiResponse(code = 403, message = "禁止访问")
})
@GetMapping("/")
public List<User> getUserList() {
    return userRepository.findAll();
}

3、返回新的数据类型

在Swagger中，我们可以在ResponseBoby注解中使用ResponseContainer注解定义响应数据的格式，常见的格式有List、Set、Map、具体类等。

@ApiOperation(value = "获取用户列表")
@ApiResponses(value = {
    @ApiResponse(code = 200, message = "获取成功", response = User.class, responseContainer = "List")
})
@GetMapping("/")
public List<User> getUserList() {
    return userRepository.findAll();
}

五、Swagger-UI的使用

Swagger-UI是Swagger的前端框架，可以通过Swagger生成的json或yaml文件来展示API文档。

1、引入Swagger-UI的依赖。

<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>swagger-ui</artifactId>
    <version>2.1.4</version>
</dependency>

2、在Spring Boot的配置文件中配置Swagger-UI的访问路径。

spring.mvc.static-path-pattern=/swagger/**
spring.resources.static-locations=classpath:/META-INF/resources/webjars/

3、启用Swagger-UI

在SwaggerConfig类中添加以下代码：

@Bean
public Docket createApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))
            .paths(PathSelectors.any())
            .build();
}

@Bean
public UiConfiguration getUiConfig() {
    return UiConfigurationBuilder.builder()
            .docExpansion(SwaggerUiConfiguration.DocExpansion.LIST)
            .build();
}

4、访问Swagger-UI

启动Spring应用，访问http://localhost:8080/swagger-ui.html，即可看到Swagger-UI的展示界面。

六、总结

本文详细阐述了Swagger的概念、快速上手、常用注解、高级用法以及Swagger-UI的使用，是学习Swagger的不错教程。