Swagger2 简记

目录

1. Swagger 简介

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

2. 作用

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

3. 整合

• 在 api 子工程添加依赖 （Swager2\Swagger UI）

  <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>
  
  

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

  • 新建 config 包，SwaggerConfig类

  
  @Configuration
  @EnableSwagger2 //启动Swagger2
  public class SwaggerConfig {
      /*swagger 帮助我们生成帮助文档
       * 1.配置生成的文档信息
       * 2.配置生成的规则
       * Docket,封装接口文档信息
       * */
      public Docket getDocket() {
          //DocumentationType.SWAGGER_2 :指定文档风格
          /*
           * 如何获取一个接口、抽象类对象
           * 1.new 接口，需要在构造器后的{}实现接口中的所有抽象方法
           * 2.new 子类/实现类
           * 3.工厂模式
           * */
  
          ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
          //创建封面信息对象
          apiInfoBuilder.title("《锋迷商城》接口说明")
                  .description("此接口文档实现了.....")
                  .version("v 2.0.1")
                  .contact(new Contact("Mr.Suho", "www.cwaits.xyz", "[email protected]"));
          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

4.Swagger 注解说明

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

5. Swagger-ui 插件

• 导入插件依赖

     <!--swagger-ui 插件-->
          <dependency>
              <groupId>com.github.xiaoymin</groupId>
              <artifactId>swagger-bootstrap-ui</artifactId>
              <version>1.9.6</version>
          </dependency>
  

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

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