接口文档生成工具——swagger使用详细说明

前言

当前后端分离开发已经成为业内的主流，这种开发方式可以让前后端更加专注自身的工作，双方往往约定好入参和出参并编写接口文档，从而完成页面对数据的顺利获取。但是随着开发时间不断变长，当代码被修改后相对应的接口文档往往没有得到及时的更新，同时接口数量越来越多，也让接口文档的维护变得更加困难。
Swagger提供描述、生产、消费和可视化RESTful Web Service，通过可视化的接口文档和便捷的开发方式，让我们能够便捷的实现接口文档的编写，同时也能方便后端开发人员对自身的接口进行自测。
swagger官网：https://swagger.io

一、Swagger的使用

1. 引入依赖

<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

我们可以通过提供一个Docket来配置swagger-ui的初始化页面信息

package com.xiaoming.swaggerdemo;

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

@EnableSwagger2
@Configuration
public class SwaggerConfig {


    /**
     * 这里的话，主要是用于初始化swagger页面的一些相关参数
     *  Docket的配置采用的是链式调用的方式，因此配置起来比较简单顺畅
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xiaoming.swaggerdemo.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                .title("SpringBoot整合Swagger") // 页面标题
                .description("SpringBoot整合Swagger的详细信息") // 页面详细信息
                .version("2.9.2")  // 版本号
                .contact(new Contact("小明","https://www.jianshu.com/u/646f454e5c0d","222@qq.com")) // 个人信息，用于页面上的联系方式展示
                .license("The Apache License")
                .licenseUrl("http://www.baidu.com") // 许可证链接地址
                .build());  // 使用build方法完成构建
    }
}

3. 在我们的接口上使用swagger的注解

package com.xiaoming.swaggerdemo.controller;

import com.xiaoming.swaggerdemo.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

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


    @PostMapping("/getUser")
    @ApiOperation("获取用户的接口")
    @ApiImplicitParam(name="id",value = "用户id",defaultValue = "123",required = true)
    public ResponseResult getUserById(String id){
        return new ResponseResult(new User("小明","男"));
    }

    @PostMapping("/saveUser")
    @ApiOperation("保存用户的接口")

    public ResponseResult registUser(@RequestBody User user){
        return new ResponseResult(null);
    }
}

4. 启动springboot项目，查看我们的swagger页面

http://localhost:8986/swagger-ui.html（端口根据实际项目情况去调整）

image.png

其他类的代码

User类

package com.xiaoming.swaggerdemo.pojo;

public class User {
    /**
     * 姓名
     */
    private String name;
    /**
     * 性别
     */
    private String sex;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getSex() {
        return sex;
    }

    public void setSex(String sex) {
        this.sex = sex;
    }

    public User(String name, String sex) {
        this.name = name;
        this.sex = sex;
    }
}

ResponseResult类

package com.xiaoming.swaggerdemo.controller;

public class ResponseResult {
    /**
     * 状态码
     */
    private String code;
    /**
     * 返回信息
     */
    private String msg;
    /**
     * 返回对象
     */
    private Object data;

    public String getCode() {
        return code;
    }

    public void setCode(String code) {
        this.code = code;
    }

    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }

    public Object getData() {
        return data;
    }

    public void setData(Object data) {
        this.data = data;
    }

    public ResponseResult(Object data) {
        this.code = "200";
        this.msg="OK";
        this.data = data;
    }
}

二、swagger常用注解的具体说明

@Api 定义在接口类上，用于标记一个接口的作用
@ApiOperation 定义在方法上，用于标记接口方法的作用
@ApiImplicitParam 用于描述一个参数
defaultValue：默认值
required：参数是否为必填项
@ApiImplicitParams 如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
如果参数是一个对象，可以参考下面的swagger注解

@ApiModel(value = "User对象",description = "这是User对象")
public class User {
    /**
     * 姓名
     */
    @ApiModelProperty(value = "姓名",required = true,example = "小明",name = "username")
    private String name;
    /**
     * 性别
     */
    @ApiModelProperty(value = "性别",required = false,example = "男",name = "sex")
    private String sex;
}

@ApiModel 定义在model上，用于描述对象
@ApiModelProperty 定义在对象的属性上，描述属性的具体信息
点击右上角Try it out ，就可以测试我们编写好的接口

image.png

三、注意事项

swagger的使用虽然可以让接口文档得到更好的维护和展示，但是在生产环境中，我们往往是不对外展示我们的接口页面的，具体如何关根据开发环境和生产环境来选择性的开放我们的swagger-ui页面，后面有空的话我会再写一篇文章来讲讲。