什么是Swagger?

Swagger是一款流行的RESTful API文档生成工具，它支持多种编程语言和多种框架，包括但不限于Java、Python、Node.js、Go等，Spring Boot也提供了对Swagger的支持。Swagger可以根据注解生成API文档，支持在线测试API接口、生成客户端代码等多种功能。

Swagger如何使用

在使用Swagger之前，我们首先需要在pom中添加依赖：

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

其中，springfox-swagger2用于定义API信息，springfox-swagger-ui用于提供展示API文档的页面。

在Spring Boot中，我们需要添加一个Swagger配置类：

import io.swagger.annotations.ApiOperation;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 创建接口api
     * @return
     */
    @Bean
    public Docket apiDocket() {
        return new Docket(DocumentationType.SWAGGER_2) // 指定生成的文档的类型是Swagger2
//                .pathMapping("/swagger") // 通过接口直接访问swagger，不配置的话默认使用/swagger-ui.html访问
                .select()
                // 生成接口api的方式一
                .apis(RequestHandlerSelectors.basePackage("org.example.ctrl")) // 需要应用的接口所在的包,可以添加多个在不同包下的ctrl
//                .apis(RequestHandlerSelectors.basePackage("org.example.ctrl"))
                // 生成接口api的方式二
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) // 扫描所有使用了@Api注解的接口类,用这种方式生成api更灵活
                // 扫描所有 .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    /**
     * 设置摘要信息
     * @return
     */
    private ApiInfo apiInfo() {
        // 用ApiInfoBuilder进行摘要定制
        return new ApiInfoBuilder()
                .title("接口示例API") // 设置标题
                .description("项目demo接口示例API模板") // 描述
                .contact(new Contact("demoAuth","https://blog.csdn.net/MrBInsomnia?spm=1000.2115.3001.5343","121@163.com")) // 设置作者信息、联系方式：Contact(String name, String blogUrl, String email)
                .version("1.0.0") // 版本
                .build();
    }
}

其中，@EnableSwagger2注解开启Swagger功能。在createRestApi()方法中，我们配置了API信息以及扫描的Controller包路径，之后就可以通过访问http://localhost:port/swagger-ui.html来查看并测试API接口了。

如何使用Swagger

首先，在Controller中，我们可以通过各种注解来标记接口信息，如下所示：

@Controller
@Api(tags = "Http渠道数据同步规范示例接口", description = "Http渠道数据同步规范示例接口 | 测试接口", hidden = false)
public class HTTPSyncController {
    @Autowired
    private UserMongoService userMongoService;

    @GetMapping("/getUsers")
    @ResponseBody
    @ApiOperation(value = "获取用户列表", notes = "获取所有用户列表信息")
    public List getUsers() {
        return userMongoService.getUsers();
    }
    @RequestMapping(value = "/data/user/syncpost", method = RequestMethod.POST)
    @ApiOperation(value = "用户新增", notes = "同步用户新增信息")
    public void syncuserpost(@RequestBody String data, HttpServletResponse response, HttpServletRequest request) {
        try {
            userMongoService.add(data);
            response.setStatus(200); // 设置状态码为 200
            response.getWriter().write("同步成功！"); // 设置响应数据为 "Hello World!"
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
    @RequestMapping(value = "/data/user/syncdel/{id}", method = RequestMethod.DELETE)
    @ApiOperation(value = "用户删除", notes = "同步用户删除信息")
    public void syncuserdel(@PathVariable String id, HttpServletResponse response, HttpServletRequest request) {
        try {
            userMongoService.del(id);
            response.setStatus(200); // 设置状态码为 200
            response.getWriter().write("同步成功！"); // 设置响应数据为 "Hello World!"
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

}

以下是一些常用参数说明：

@Api 修饰整个类，描述Controller的作用。
@ApiOperation 修饰一个类的一个方法，或者说一个接口，可以描述这个方法的功能和注意事项。若不使用则用函数名作为方法功能。
参数：value="说明方法的用途、作用"

notes="方法的备注说明"

@apiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类

@ApiImplicitParams 修饰方法，可以描述这个方法的参数的作用。若不使用则用参数名作为参数的作用。
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
@ApiModel 修饰实体类，可以描述这个类的功能。
@ApiModelProperty 修饰实体类的属性，可以描述这个属性的作用。
@ApiIgnore修饰参数、方法和类，可以在自动生成文档时对修饰的对象进行忽略。
@ApiError ：发生错误返回的信息