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

简介

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

实战应用

引入相关依赖

 <properties>
        <swagger.version>2.9.2</swagger.version>
 </properties>
    
 <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
 </dependencies>    

swagger配置

application.yml配置文件

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

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();
    }
}

注解描述

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();
  }

}

模型类注解

常用注解

• @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;
    }
}   

查看API接口文档

访问接口文档页面

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

查看添加用户接口描述

查看模型类描述

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

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

添加<T>让类变成泛型类

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

设置data为泛型属性

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

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

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

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

查看效果

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

项目配套代码

github地址
要是觉得我写的对你有点帮助的话,麻烦在github上帮我点 Star

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

• 1.搭建第一个springboot项目
• 2.Thymeleaf模板引擎实战
• 3.优化代码,让代码更简洁高效
• 4.集成jta-atomikos实现分布式事务
• 5.分布式锁的实现方式
• 6.docker部署,并挂载配置文件到宿主机上面
• 7.项目发布到生产环境
• 8.搭建自己的spring-boot-starter
• 9.dobbo入门实战
• 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风格的接口文档