SpringBoot整合Swagger

1. 添加依赖包

   <dependency>
       <groupId>com.spring4all</groupId>
       <artifactId>swagger-spring-boot-starter</artifactId>
       <version>1.7.1.RELEASE</version>
   </dependency>

2. 开启Swagger

   在 *Application 类上面启用注解

   @EnableSwagger2Doc

3. 一般用法（网上后很多资料，这里不再赘述）

   @RestController
   @RequestMapping("/community")
   @Api(value = "/community", description = "小区相关操作")
   public class CommunityController {
   
       private final ResultObject resultObject;
   
       @Autowired
       public CommunityController(ResultObject resultObject) {this.resultObject = resultObject;}
   
       @RequestMapping(value = "", method = RequestMethod.DELETE)
       @ApiOperation(value = "删除小区（删除顺序：id、cityId、address）")
       @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "小区编号", dataType = "string"), @ApiImplicitParam(name =
               "cityId", value = "所属城市编号", dataType = "string"), @ApiImplicitParam(name = "address", value = "小区地址",
               dataType = "string")})
       public ResultObject remove(String id, String cityId, String address) {
           return resultObject;
       }
   
       @RequestMapping(value = "", method = RequestMethod.PUT)
       @ApiOperation(value = "更新小区地址")
       @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "小区编号", dataType = "string", required = true),
               @ApiImplicitParam(name = "cityId", value = "新的城市编号", dataType = "string"), @ApiImplicitParam(name =
               "address", value = "新的小区地址", dataType = "string")})
       public ResultObject update(@RequestParam String id, String cityId, String address) {
           return resultObject;
       }
   }

4. 解决实际项目中一般用法遇到的不足（自定义requestBody参数）

   定义一个模型类（getter和setter必须要有）

   @ApiModel(value = "swaggerModel", description = "Swagger Model Demo")
   public class SwaggerModel {
   
       @ApiModelProperty(value = "编号", required = true)
       private String id;
   
       @ApiModelProperty(value = "名字", required = true)
       private String name;
   
       public String getId() {
           return id;
       }
   
       public void setId(String id) {
           this.id = id;
       }
   
       public String getName() {
           return name;
       }
   
       public void setName(String name) {
           this.name = name;
       }
   }   

   创建一个测试的控制器

   @RestController
   @RequestMapping("/swagger")
   @Api(value = "/swagger", description = "swagger demo")
   public class SwaggerController {
   
       @RequestMapping(value = "", method = RequestMethod.GET)
       @ApiOperation("测试")
       public String test(@RequestBody @ApiParam SwaggerModel swaggerModel) {
           return "200 ok";
       }
   }

   效果如下：

   

5. 自定义返回内容

   定义模型类

   public class ResultObject<T> {
   
       private Integer code;
   
       private String message;
   
       private String status;
   
       private T data;
   
       ... setter and getter
   }

   假设有这样一个数据传输对象

   /**
    * 这里用到了lombok插件
    **/
   @Data
   @NoArgsConstructor
   @AllArgsConstructor
   @ApiModel(value = "image", description = "图片信息")
   public class ImageVO implements Serializable {
   
       @ApiModelProperty(value = "图片编号")
       private Long id;
   
       @ApiModelProperty(value = "图片访问链接")
       private String url;
   
       @ApiModelProperty(value = "图片标签")
       private String tag;
   }

   我们还需要写一个Controller接口来测试

   @RequestMapping(value = "/upload", method = RequestMethod.POST)
   @ApiOperation("上传图片（上传成功会返回图片的URL）")
   @ApiImplicitParams({@ApiImplicitParam(name = "image", value = "图片", required = true, dataTypeClass =
           MultipartFile.class), @ApiImplicitParam(name = "tag", value = "图片标签")})
   public ResultObject<ImageVO> upload(@RequestBody MultipartFile image, String tag) throws IOException {
       return new ResultObject<>();
   }

   效果如下：