【SpringBoot框架篇】17.使用swagger2生成RESTful风格的接口文档

1.简介

现如今，前后端分离已经逐渐成为互联网项目一种标准的开发方式，前端与后端交给不同的人员开发，
但是项目开发中的沟通成本也随之升高，这部分沟通成本主要在于前端开发人员与后端开发人员对WebAPI接口的沟通，Swagger2 就可以很好地解决，它可以动态生成Api接口文档，降低沟通成本，促进项目高效开发。

2.实战应用

2.1.引入相关依赖

 
        2.9.2
 
    
 
        
            org.springframework.boot
            spring-boot-starter-web
        
        
            io.springfox
            springfox-swagger2
            ${swagger.version}
        
        
            io.springfox
            springfox-swagger-ui
            ${swagger.version}
        
     

2.2.swagger配置

2.2.1.application.yml配置文件

#生产环境改成false禁用
server:
 port: 8017
swagger:
  enable: true

2.2.2.swagger配置类

• @ConditionalOnProperty 注解用于动态加载配置类

• 通过其两个属性name以及havingValue来实现的，其中name用来从application.properties中读取某个属性值。
• 如果该值为空，则返回false;
• 如果值不为空，则将该值与havingValue指定的值进行比较，如果一样则返回true;否则返回false。
• 如果返回值为false，则该configuration不生效(不会加载该类)；为true则生效。

@Configuration
@EnableSwagger2
@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
public class SwaggerConfig {

    /**
     * swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
     * @return Docket
     */
    @Bean(value = "defaultApi")
    public Docket defaultApi() {
        //添加header参数
        ParameterBuilder ticketPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        ticketPar.name("token")
                .description("用户登录获取的token信息")
                .modelRef(new ModelRef("string")).parameterType("header")
                //header中的参数是非必填的。
                .required(false).build();
        pars.add(ticketPar.build());
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                // 为当前包路径
	                .apis(RequestHandlerSelectors.basePackage("com.ljm.boot.swagger"))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .groupName("需要token验证")
                .globalOperationParameters(pars);
    }


    /**
     * api文档的详细信息函数,注意这里的注解引用的是哪个
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // //大标题
                .title("【SpringBoot框架篇】 17.swagger对接口文档进行管理")
                // 版本号
                .version("1.0")
               .termsOfServiceUrl("NO terms of service")
                // 描述
                .description("本教程配套代码github地址:https://github.com/Dominick-Li/springboot-master")
                //作者
                .license("The Apache License, Version 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .build();
    }
}

2.3.注解描述

2.3.1.API接口注解

常用注解

• @Api : 用在类上，描述该类的主要作用。
• @ApiOperation：用在方法上，描述该方法主要作用。
• @ApiImplicitParams : 用在方法上，包含一组参数说明。
• @ApiImplicitParam: 用在方法上，用于描述一个参数说明

@ApiImplicitParam参数说明

属性	描述
name	参数名
value	参数的描述信息
defaultValue	默认值
required	必选？ (默认值false) ,设置true该参数必须填写

测试用例

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

  @GetMapping("/")
  @ApiOperation("分页查询所有用户")
  public List<User> getUserById(@RequestBody PageParam pageParam) {
      return new ArrayList<User>();
  }

  @GetMapping("/{id}")
  @ApiOperation("根据id查询用户的接口")
  @ApiImplicitParam(name = "id", value = "用户id", required = true)
  public User getUserById(@PathVariable Integer id) {
     return new User();
  }


  @PostMapping("/")
  @ApiOperation("添加用户的接口")
  @ApiImplicitParams({
          @ApiImplicitParam(name = "username", value = "用户名", defaultValue = "李四"),
          @ApiImplicitParam(name = "address", value = "用户地址", defaultValue = "北京", required = true)
  })
  public HttpResult addUser(String username, @RequestParam(required = true) String address) {
      return HttpResult.successResult();
  }

  @PutMapping("/{id}")
  @ApiOperation("根据id更新用户的接口")
  public HttpResult updateUserById(@RequestBody User user) {
      return HttpResult.successResult();
  }

}

2.3.2.模型类注解

常用注解

• @ApiModel 描述该类的信息
• @ApiModelProperty 描述该属性的信息

测试用例

@ApiModel("用户类")
public class User {
    @ApiModelProperty("用户唯一id")
    private Integer id;

    @ApiModelProperty("用户名")
    private String username;

    @ApiModelProperty("密码")
    private String password;

    @ApiModelProperty("地址")
    private String address;
    //省略get set方法
} 
@ApiModel("Http结果响应")
public class HttpResult  implements Serializable {

    private static String successMessage = "操作成功";

    private static String errorMessage = "操作失败";

    @ApiModelProperty("响应码")
    private int code;

    @ApiModelProperty("响应数据")
    private Object data;

    @ApiModelProperty("响应消息")
    private String msg;

    public HttpResult(){ }

    public HttpResult(int code, String msg) {
        this.code=code;
        this.msg=msg;
    }

    public HttpResult(int code, String msg, Object data) {
        this.code=code;
        this.msg=msg;
        this.data=data;
    }

    public int getCode() {
        return code;
    }

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

    public Object getData() {
        return data;
    }

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

    public String getMsg() {
        return msg;
    }

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

    public static HttpResult successResult() {
        return new HttpResult(HttpStatus.OK.value(), successMessage);
    }

    public static HttpResult successResult(String msg) {
        return new HttpResult(HttpStatus.OK.value(), defaultSuccessMsg(msg));
    }

    public static HttpResult successResult(Object obj) {
        return new HttpResult(HttpStatus.OK.value(), successMessage, obj);
    }

    public static HttpResult successResult(String msg, Object obj) {
        return new HttpResult(HttpStatus.OK.value(), defaultSuccessMsg(msg), obj);
    }

    public static HttpResult failureResult() {
        return new HttpResult(HttpStatus.INTERNAL_SERVER_ERROR.value(), errorMessage);
    }

    public static HttpResult failureResult(String msg) {
        return new HttpResult(HttpStatus.INTERNAL_SERVER_ERROR.value(), defautlErrorMsg(msg));
    }

    public static HttpResult failureResult(Integer code, String msg) {
        return new HttpResult(code, defautlErrorMsg(msg));
    }

    public static HttpResult failureResult(String msg, Object obj) {
        return new HttpResult(HttpStatus.INTERNAL_SERVER_ERROR.value(), defaultSuccessMsg(msg), obj);
    }

    private static String defautlErrorMsg(String msg) {
        return StringUtils.isEmpty(msg)?errorMessage:msg;

    }

    private static String defaultSuccessMsg(String msg) {
        return StringUtils.isEmpty(msg)?successMessage:msg;
    }
}   

3.查看API接口文档

3.1.访问接口文档页面

访问http://localhost:8017/swagger-ui.html查看API接口文档

3.2.查看添加用户接口描述

3.3.查看模型类描述

4.解决ApiModel类作为属性返回没有显示类描述

4.1.改造上面的HttpResult数据返回封装类

4.1.1.添加让类变成泛型类

@ApiModel("Http结果响应")
public class HttpResult<T> implements Serializable {}

4.1.2.设置data为泛型属性

 @ApiModelProperty("响应数据")
    private T data;
    public T getData() {
        return data;
    }

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

4.1.3.接口返回的时候指定返回类型

 @GetMapping("/{id}")
 public HttpResult<User> getUserById(@PathVariable Integer id) {
       return HttpResult.successResult(new User());
 }

4.2.查看效果

重新启动项目查看接口描述,看到data属性里已经变成了ApiModel类了。

5.项目配套代码

github地址

创作不易,要是觉得我写的对你有点帮助的话,麻烦在github上帮我点下 Star

【SpringBoot框架篇】其它文章如下,后续会继续更新。

• 1.搭建第一个springboot项目
• 2.Thymeleaf模板引擎实战
• 3.优化代码,让代码更简洁高效
• 4.集成jta-atomikos实现分布式事务
• 5.分布式锁的实现方式
• 6.docker部署,并挂载配置文件到宿主机上面
• 7.项目发布到生产环境
• 8.搭建自己的spring-boot-starter
• 9.dubbo入门实战
• 10.API接口限流实战
• 11.Spring Data Jpa实战
• 12.使用druid的monitor工具查看sql执行性能
• 13.使用springboot admin对springboot应用进行监控
• 14.mybatis-plus实战
• 15.使用shiro对web应用进行权限认证
• 16.security整合jwt实现对前后端分离的项目进行权限认证
• 17.使用swagger2生成RESTful风格的接口文档
• 18.使用Netty加websocket实现在线聊天功能
• 19.使用spring-session加redis来实现session共享
• 20.自定义@Configuration配置类启用开关
• 21.对springboot框架编译后的jar文件瘦身
• 22.集成RocketMQ实现消息发布和订阅
• 23.集成smart-doc插件零侵入自动生成RESTful格式API文档
• 24.集成FastDFS实现文件的分布式存储