Swagger使用注意事项-java

登录后复制

          
          

           
           使用swagger后，所有controller中的方法都会自动生成接口；但是并不完美，需要配合swagger的注解来进行接
           
           
口说明的完善(在代码中添加了注释，方便阅读)。可以导入到Yapi中，免去手动创建接口的麻烦。
          
          

• 1.
• 2.

一、类说明

登录后复制

          
          

           
           @Api(
           
           value
           
           =
           
           "描述", 
           
           tags
           
           =
           
           "分类")
          
          

• 1.

tags用于分类使用，可以合并多个不同controller。

二、方法说明

登录后复制

          
          

           
           @ApiOperation(
           
           value
           
           =
           
           "方法描述", ....)
          
          

• 1.

如果需要添加其他说明，可以直接进入该注释查看

三、请求入参

登录后复制

          
          

           
           分两部分，可以使用@ApiImplicitParam ， @ApiParam 和 @ApiModel来使用
          
          

• 1.

3.1、@ApiImplicitParam

与@ApiImplicitParams配合使用

登录后复制

          
          

           
           @ApiImplicitParams({
           
           

           
           

           
           @ApiImplicitParam(
           
           name 
           
           = 
           
           "path", 
           
           value 
           
           = 
           
           "文件名(全路径)", 
           
           required 
           
           = 
           
           true,
           
           

           
           

           
           paramType 
           
           = 
           
           "body"),
           
           

           
           

           
           @ApiImplicitParam(
           
           name 
           
           = 
           
           "content", 
           
           value 
           
           = 
           
           "文件内容", 
           
           required 
           
           = 
           
           true,
           
           

           
           

           
           paramType 
           
           = 
           
           "body"),
           
           

           
           

           
           @ApiImplicitParam(
           
           name 
           
           = 
           
           "encoding", 
           
           value 
           
           = 
           
           "编码格式", 
           
           defaultValue 
           
           = 
           
           "UTF8", 
           
           paramType 
           
           = 
           
           "body"),
           
           

           
           

           
           @ApiImplicitParam(
           
           name 
           
           = 
           
           "override", 
           
           value 
           
           = 
           
           "是否覆盖，默认true",
           
           

           
           

           
           defaultValue 
           
           = 
           
           "true", 
           
           paramType 
           
           = 
           
           "body"),
           
           

           
           
})
          
          

• 1.
• 2.
• 3.
• 4.
• 5.
• 6.
• 7.
• 8.
• 9.
• 10.
• 11.
• 12.
• 13.
• 14.
• 15.
• 16.
• 17.

3.2、@ApiParam

在方法的入参上使用

登录后复制

          
          

           
           示例：
           
           @ApiOperation(
           
           value 
           
           = 
           
           "本地文件上传")
           
           

           
           

           
           @ApiImplicitParams({
           
           

           
           

           
           @ApiImplicitParam(
           
           name 
           
           = 
           
           "path", 
           
           value 
           
           = 
           
           "文件上传的路径", 
           
           required 
           
           = 
           
           true,
           
           

           
           

           
           dataType 
           
           = 
           
           "string", 
           
           paramType 
           
           = 
           
           "form"),
           
           

           
           
})
           
           

           
           

           
           @ApiResponses(
           
           @ApiResponse(
           
           code 
           
           = 
           
           200, 
           
           message 
           
           = 
           
           "处理成功"))
           
           

           
           

           
           @PostMapping(
           
           consumes 
           
           = 
           
           MediaType.
           
           MULTIPART_FORM_DATA_VALUE)
           
           

           
           

           
           public 
           
           ApiCommonResult
           
           <
           
           List
           
           <
           
           FileDTO
           
           >> 
           
           upload(
           
           @RequestParam 
           
           String 
           
           path,
           
           

           
           

           
           @ApiParam(
           
           value 
           
           = 
           
           "文件", 
           
           required 
           
           = 
           
           true) 
           
           @RequestParam 
           
           List
           
           <
           
           MultipartFile
           
           > 
           
           files) {
           
           

           
           
}
          
          

• 1.
• 2.
• 3.
• 4.
• 5.
• 6.
• 7.
• 8.
• 9.
• 10.
• 11.
• 12.
• 13.
• 14.
• 15.
• 16.
• 17.
• 18.
• 19.

3.3、@ApiModel

对象上使用，具体成员变量使用@ApiModelProperty

示例：

登录后复制

          
          

           
           /**
           
           

           
           • @ClassName: FileVO
           
           

           
           • @Description:
           
           

           
           • @Author: zhengya_wu
           
           

           
           • @Date: 2020/10/9 19:27
           
           

           
           • @Version: 1.0
           
           

           
           

           
           */
           
           

           
           

           
           @Data
           
           

           
           

           
           @ApiModel(
           
           value 
           
           = 
           
           "FileVO", 
           
           description 
           
           = 
           
           "文件信息")
           
           

           
           

           
           public 
           
           class 
           
           FileVO {
           
           

           
           

           
           @ApiModelProperty(
           
           value 
           
           = 
           
           "文件名(全路径)", 
           
           required 
           
           = 
           
           true)
           
           

           
           

           
           @NonNull
           
           

           
           

           
           String 
           
           path;
           
           

           
           

           
           @ApiModelProperty(
           
           value 
           
           = 
           
           "文件内容", 
           
           required 
           
           = 
           
           true)
           
           

           
           

           
           @NonNull
           
           

           
           

           
           String 
           
           content;
           
           

           
           

           
           @ApiModelProperty(
           
           value 
           
           = 
           
           "编码格式", 
           
           example 
           
           = 
           
           "UTF-8")
           
           

           
           

           
           String 
           
           encoding 
           
           = 
           
           "UTF-8";
           
           

           
           

           
           @ApiModelProperty(
           
           value 
           
           = 
           
           "是否覆盖，默认true", 
           
           example 
           
           = 
           
           "true")
           
           

           
           

           
           boolean 
           
           override 
           
           = 
           
           true;
           
           

           
           
}
          
          

• 1.
• 2.
• 3.
• 4.
• 5.
• 6.
• 7.
• 8.
• 9.
• 10.
• 11.
• 12.
• 13.
• 14.
• 15.
• 16.
• 17.
• 18.
• 19.
• 20.
• 21.
• 22.
• 23.
• 24.
• 25.
• 26.
• 27.
• 28.
• 29.
• 30.
• 31.
• 32.
• 33.
• 34.
• 35.
• 36.

使用：

登录后复制

          
          

           
           • 
           
           @ApiOperation(
           
           "保存代码")
           
           

           
           

           
           @ApiResponses(
           
           @ApiResponse(
           
           code 
           
           = 
           
           200, 
           
           message 
           
           = 
           
           "处理成功"))
           
           

           
           

           
           @PutMapping(
           
           consumes 
           
           = 
           
           MediaType.
           
           APPLICATION_JSON_UTF8_VALUE)
           
           

           
           

           
           public 
           
           ApiCommonResult 
           
           write(
           
           @RequestBody 
           
           FileVO 
           
           params) {
           
           

           
           
}
          
          

• 1.
• 2.
• 3.
• 4.
• 5.
• 6.
• 7.
• 8.
• 9.

四、结果说明

4.1、具体类型

直接使用3.3描述类信息即可

4.2、范型

需要特殊定义，所有类都要使用@ApiModel注解，并且在方法上添加@ApiResponse; 但是一定要去除 response

五、效果

5.1、URL头中

5.2、请求体中

六、参考示例

webideall/web‑ide/src/main/java/com/ict/sass/codemanage

七、注意点

7.1、上传文件

登录后复制

          
          

           
           上传文件，在swagger自带ui中显示正常，但是导入导Yapi中，显示异常；所以如果是多文件上传，使用list或者
           
           

           
           数组接收，需要手动在Yapi中修改；如果是单文件上传，无需手动修改；可以参考示例代码
          
          

• 1.
• 2.

7.2、结果返回类型为范型或者Object

登录后复制

          
          

           
           只需要所有类上加上
           
           @ApiModel
           
           注解；并且在
           
           @ApiResponse
           
           中不要定义response
          
          

• 1.

注意：目前在工程中创建了新的范型类 ApiCommonResult

八、访问

8.1、直接使用swagger自带ui

登录后复制

          
          

           
           http:
           
           //ip:port/swagger-ui.html
          
          

• 1.

8.2、使用三方ui

登录后复制

          
          

           
           http:
           
           //ip:port/doc.html
          
          

• 1.

8.3、使用Yapi

登录后复制

          
          

           
           http:
           
           //172.16.2.164:300
          
          

• 1.