Swagger2 简记

• • • 目录
    • • • 1. Swagger 简介
        • 2. 作用
        • 3. 整合
        • 4.Swagger 注解说明
        • 5. Swagger-ui 插件

前后端分离开发，后端需要编写接口说明文档，耗费时间，swagger 是一个用于`生成服务器接口的规范性文档，并且能够对接口进行测试的工具

• 生成服务器接口的规范性文档
• 对接口进行测试

• 在 api 子工程添加依赖 （Swager2Swagger UI）

  
      io.springfox
      springfox-swagger2
      2.9.2
  
  
      io.springfox
      springfox-swagger-ui
      2.9.2
  
  
  

• 在 api 子工程创建 swagger 的配置（Java配置方式）

  • 新建 config 包，SwaggerConfig类

  @Configuration
  @EnableSwagger2 //启动Swagger2
  public class SwaggerConfig {
      
      public Docket getDocket() {
          //DocumentationType.SWAGGER_2 :指定文档风格
          
  
          ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
          //创建封面信息对象
          apiInfoBuilder.title("《锋迷商城》接口说明")
                  .description("此接口文档实现了.....")
                  .version("v 2.0.1")
                  .contact(new Contact("Mr.Suho", "www.cwaits.xyz", "cwaits@163.com"));
          ApiInfo apiInfo = apiInfoBuilder.build();
          Docket docket = new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo)//指定生成的文档封面信息：文档标题，版本。作者
                  .select()
                  .apis(RequestHandlerSelectors.basePackage("com.sh.controller"))
                  .paths(PathSelectors.regex("/user/"))
                  .build();
          return docket;
      }
  }
  
  

• 测试

  • 启动 SpringBoot 应用，访问：http://localhost:8080/swagger-ui.html

swagger 提供了一套注解，可以对每个接口进行详细说明

• @api（类注解），在控制器类添加此注解，可以对控制器进行说明

  @Api(value = "实现用户登录，注册功能",tags = "用户管理")
  

• @ApiImpliciParams 和 @ApiImpliciParam （方法注解），说明接口方法的参数

     @ApiImplicitParams({
              @ApiImplicitParam(dataType ="String",name = "username",value = "用户登录账号",required = true),
              @ApiImplicitParam(dataType ="String",name = "pwd",value = "用户登录密码",required = false),
      })
      @RequestMapping(value = "/login",method = RequestMethod.GET)
      public ResultVo login(String name, String pwd){
         return userService.checkLogin(name,pwd);
      }
  
  

• @ApiOperation（方法注解），说明接口方法的作用

   @ApiOperation("用户登录接口")
     @RequestMapping(value = "/login",method = RequestMethod.GET)
      public ResultVo login(String name, String pwd){
         return userService.checkLogin(name,pwd);
      }
  

• @ApiModel 和 @ApiModelProperty，当接口参数和返回值为对象类型时，在实体类中添加注解说明

  @ApiModel(value = "ResultVO对象",description = "封装接口返回给前端的数据")
  public class ResultVo {
      //响应给前端的状态码
      @ApiModelProperty(value = "响应状态码",dataType = "int")
      private Integer code;
      //响应给前端的提示信息
      @ApiModelProperty("响应提示信息")
      private String msg;
      //响应给前端的数据
      @ApiModelProperty("响应数据")
      private Object data;
  }
  

• @ApiIgnore，接口方法注解，添加此注解的方法将不会生成到接口文档中

   @ApiIgnore
      @RequestMapping(value = "/login",method = RequestMethod.GET)
      public ResultVo login(String name, String pwd){
         return userService.checkLogin(name,pwd);
      }
  

• 导入插件依赖

     
          
              com.github.xiaoymin
              swagger-bootstrap-ui
              1.9.6
          
  

• 文档访问：http://ip:port/doc.html

  • http://localhost:8080/doc.html