什么是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);
        }
    }

}

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