前言

1. 前端经常抱怨后端给的接口文档与实际情况不一致。
2. 后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。

3. 其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。

   
   
   在这里插入图片描述

1.什么是Swagger2?它能干什么？

1. 发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是Swagger的由来。
2. 通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。
3. 这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。

2.Swagger2的优点

1. Swagger2的出现解决了上述问题。它作为一个规范和完整的框架，可以用于生成、描述、调用和可视化RESTful风格的Web服务。
2. 接口文档在线自动生成，文档随接口变动实时更新，节省维护成本。
3. 支持在线接口测试，不依赖第三方工具。

上面介绍完了Swagger2，那接下来就开始使用它。这里使用SpringBoot2.X集成Swagger2。

3.引入Swagger2的依赖

使用Swagger2只需要引入下面两个依赖即可：

...
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
省略了SpringBoot相关的依赖...

4.配置Swagger2

下面简单说明该配置的作用

1. 通过@Configuration注解，让 Spring加载该配置类。再通@EnableSwagger2注解来启用Swagger2。
2. 成员方法 createRestApi 函数创建 Docket 的Bean之后，apiInfo() 用来创建该 Api 的基本信息（这些基本信息会展现在文档页面中）。select()返回一个 ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，Swagger会扫描该包下所有 Controller类定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

@EnableSwagger2
@Configuration
public class Swagger2Config {

    //api接口包扫描路径
    public static final String SWAGGER_SCAN_BASE_PACKAGE = "cn.zwq.controller";

    //Swagger2接口文档版本
    public static final String VERSION = "1.0.0";

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .paths(PathSelectors.any()) //可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .build();
    }

    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Spring Boot 测试使用 Swagger2 构建RESTful API") //设置文档的标题
                .description("REST API")    //设置文档的描述
                .version(VERSION)   //设置文档的版本
                .termsOfServiceUrl("")  //设置文档的License信息
                .contact(new Contact("zwq","https://blog.csdn.net/weixin_44176169","Xxx@163.com"))
                .build();
    }
}

5.Swagger2注解详解

@Api：请求类的说明

@Api：放在请求的类上，与@Controller并列，说明类的作用，如用户模块，订单类等。
    tags="说明该类的作用"

@Api(tags = "用户模块")
@RestController
@RequestMapping("/user")
public class UserController {}

@ApiOperation：方法的说明

@ApiOperation："用在请求的方法上，说明方法的作用"
    value="说明方法的作用"
    notes="方法的备注说明"

@ApiOperation(value = "跳转到用户登录页面",notes = "当访问项目根路径的时候，跳转到用户登录页面")
    @RequestMapping(value = "/",method = RequestMethod.GET)
    public String login(){
        return "login";
    }

@ApiImplicitParams、@ApiImplicitParam：方法参数的说明

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
    @ApiImplicitParam：对单个参数的说明      
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（请求体）-->  @RequestBody User user
            · form（普通表单提交）     
        dataType：参数类型，默认String，其它值dataType="参数类型"       
        defaultValue：参数的默认值

@ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
        @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
})
@RequestMapping(value="/{id}", method=RequestMethod.PUT)
public void putUser(@PathVariable Long id, @RequestBody User user) {
    User u = new User();
    users.put(id, u);
}

@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@RequestMapping(value="/{id}", method=RequestMethod.GET)
public User getUser(@PathVariable Long id) {
    return users.get(id);
}

@ApiResponses、@ApiResponse：方法返回值的说明

@ApiResponses：方法返回对象的说明
    @ApiResponse：每个参数的说明
        code：数字，例如404
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiResponses({
        @ApiResponse(code = 404,message = "请求路径找不到"),
        @ApiResponse(code = 400,message = "请求参数不正确")
})
@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@RequestMapping(value="/{id}", method=RequestMethod.GET)
public User getUser(@PathVariable Long id) {
    return users.get(id);
}

@ApiModel：用于JavaBean上面，表示一个JavaBean

@ApiModel：用于JavaBean的类上面，表示此JavaBean整体的信息
    （这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）

@ApiModelProperty：用在JavaBean的属性上面，说明属性的含义

@Data
@ApiModel(value ="用户实体类",description = "封装用户信息")
public class User {
    @ApiModelProperty(name = "id",value = "用户id")
    private Long id;
    @ApiModelProperty(name = "username",value = "用户名")
    private String username;
    @ApiModelProperty(name = "password",value = "用户密码")
    private String password;
}

@ApiIgnore：使用该注解忽略这个API

//    @ApiOperation(value = "跳转到用户登录页面",notes = "当访问项目根路径的时候，跳转到用户登录页面")
@ApiIgnore
@GetMapping("/")
public String login(){
    return "login";
}

完整接口代码

@Api(tags = "用户模块")
@RestController
@RequestMapping("/user")
public class UserController extends WebMvcConfigurationSupport {
    
    //这个只是模拟存在用户数据，可以忽略
    private Map<Long,User> users = Collections.synchronizedMap(new HashMap<>());

//    @ApiOperation(value = "跳转到用户登录页面",notes = "当访问项目根路径的时候，跳转到用户登录页面")
    @ApiIgnore
    @GetMapping("/")
    public String login(){
        return "login";
    }

    @ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
            @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    })
    @PutMapping("/{id}")
    public String putUser(@PathVariable Long id, @RequestBody User user) {
        User u = new User();
        users.put(id, u);
        return "success";
    }

    @ApiResponses({
            @ApiResponse(code = 404,message = "请求路径找不到"),
            @ApiResponse(code = 400,message = "请求参数不正确")
    })
    @ApiOperation(value="创建用户", notes="根据User对象创建用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    @PostMapping("/insert")
    public String postUser(@RequestBody User user) {
        users.put(user.getId(), user);
        return "success";
    }

    @ApiResponses({
            @ApiResponse(code = 404,message = "请求路径找不到"),
            @ApiResponse(code = 400,message = "请求参数不正确")
    })
    @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return users.get(id);
    }

    @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    @DeleteMapping("/{id}")
    public String deleteUser(@PathVariable("id") Long id) {
        users.remove(id);
        return "success";
    }
}

6.Swagger2 API文档浏览地址

当上面的配置都没问题之后，就启动SpringBoot项目，访问下面地址，其中的端口改为项目的端口即可。
http://localhost:8080/swagger-ui.html

在这里插入图片描述

7.将Swagger2 API接口导入Postman

在这里插入图片描述

在这里插入图片描述

在这里插入图片描述