整合Swagger

Swagger 常用注解

在类或方法上添加 Swagger 相关注解，即可生成 Swagger 接口文档，常用注解如下:

• @Api ：用在Controller类上，描述该类的作用，注解参数：

  • value="简要说明"
  • description="详细描述该类的作用"

• @ApiOperation：用在Controller请求方法上，描述方法的作用。

• @ApiImplicitParams：用在请求方法上，对多个请求参数增加描述。

• @ApiImplicitParam：可单独使用，或在 @ApiImplicitParams 中使用，给方法的一个请求参数增加描述。

  • name：参数名
  • value：描述参数的作用
  • dataType：参数类型，默认String，其他值dataType="Integer"
  • defaultValue：参数默认值
  • required：参数是否必传（true/false）
  • paramTpye：指定参数放在哪些地方（header/query/path/body/form）
    • header ：参数在request headers 里边提交 @RequestHeader
    • query ：直接跟参数完成自动映射赋值 @RequestParam
    • path ：以路径变量的形式提交数据 @PathVariable
    • body ：以流的形式提交 仅支持POST（不常用）
    • form ：以form表单的形式提交 仅支持POST （不常用）

  如下：

  // 请求方法有多个请求参数 size， current 
  @ApiImplicitParams({  
      @ApiImplicitParam(name="current", value="页码", required=true, paramType="path", dataType="int"),  
      @ApiImplicitParam(name="size", value="每页记录数", required=true, paramType="path", dataType="int") }) 
  @ApiOperation("根据分类名称与状态查询分类列表接口") 
  @PostMapping("/search/{current}/{size}") 
  Result search(@RequestBody CategoryREQ req,
                @PathVariable int current, @PathVariable int size);
  
  

• @ApiModel：用在请求参数是对象上，描述该对象类的作用

  如下：在 CategoryREQ 类名上使用

  // 请求方法参数是 CategoryREQ 对象 
  public Result search(@RequestBody CategoryREQ req) {}
   
  // 在对象类上使用@ApiModel 
  @ApiModel(value="CategoryREQ对象", description="类别查询条件") 
  public class CategoryREQ extends BaseRequest<Category> { 
  }
  

• @ApiModelProperty：用在请求参数是对象的属性上，描述对象属性的作用。

  • value：属性的描述
  • hidden：是否是查询条件属性, false:(默认值)在api文档显示，作为查询条件；true 隐藏，不是条件属性

  // 请求方法参数是 CategoryREQ 对象 
  public Result search(@RequestBody CategoryREQ req) {}
   
  @ApiModel(value="CategoryREQ对象", description="类别查询条件") 
  public class CategoryREQ extends BaseRequest<Category> {
   
      @ApiModelProperty(value = "分类名称")    
      private String name;
   
      @ApiModelProperty(value="状态(1:正常，0:禁用)")    
      private Integer status;
   
  }
  

• @ApiResponses：用在请求的方法上，用于表示一组响应

  • @ApiResponse：用在 @ApiResponses 中，一般用于表达一个错误的响应信息，注解参数：
    • code：数字，如 400
    • message：信息，如 “参数填写错误”
    • response：抛出异常的类

• @ApiIgnore: 使用该注解忽略这个 API

Swagger 使用

1. pom.xml添加swagger依赖

   <!--swagger--> 
   <dependency>
       <groupId>com.spring4all</groupId>    
       <artifactId>swagger-spring-boot-starter</artifactId>    
       <!-- 版本号 在父工程的pom.xml已经声明了 --> 
   </dependency>
   

2. 在启动类上添加 @EnableSwagger2Doc ，启动 Swagger

   import com.spring4all.swagger.EnableSwagger2Doc; 
   import org.springframework.boot.SpringApplication; 
   import org.springframework.boot.autoconfigure.SpringBootApplication;
    
   @EnableSwagger2Doc //启动Swagger @SpringBootApplication
   public class ArticleApplication 
       public static void main(String[] args) {
           SpringApplication.run(ArticleApplication.class);
       }
   }
   

3. 在 Controller 接口中添加 Swagger 注解。

   @Api(value="分类管理接口",description = "分类管理接口，提供分类的增、删、改、查") @RestController // 所有方法的返回值转换为 Json 字符串进行响应 
   @RequestMapping("/category") 
   public class CategoryController {
    
       @Autowired    
       ICategoryService categoryService;
    
       /**     
        * 分页查询，@RequestBody 请求体中的json数据     
        * @param req 分类名与状态查询和分页参数     
        * @return     
        */    
        @ApiOperation("根据分类名称与状态查询分类列表接口")    
        @PostMapping("/search")    
        public Result search(@RequestBody CategoryREQ req) {        
            return categoryService.queryPage(req);    
        } 
   }
   

4. 在 bean 类中添加 Swagger 注解

   import com.mengxuegu.blog.entities.Category; 
   import com.mengxuegu.blog.util.base.BaseRequest; 
   import io.swagger.annotations.ApiModel; 
   import io.swagger.annotations.ApiModelProperty; 
   import lombok.Data; 
   import lombok.experimental.Accessors;
    
   @Data @Accessors(chain = true) 
   @ApiModel(value="CategoryREQ对象", description="类别查询条件") 
   public class CategoryREQ extends BaseRequest<Category> {
    
       @ApiModelProperty(value = "分类名称")    
       private String name;
       
       @ApiModelProperty(value="状态(1:正常，0:禁用)") 
       private Integer status;
   } 
   

访问Swagger

1. 重启服务
2. 访问http://127.0.0.1:8080/xxx/swagger-ui.html