Swagger使用注意事项-java

Posted 2023-02-08

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

一、类说明

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

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

二、方法说明

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

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

三、请求入参

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

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"),

)

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) 

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;

使用：

• @ApiOperation("保存代码")

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

@PutMapping(consumes = MediaType.APPLICATION_JSON_UTF8_VALUE)

public ApiCommonResult write(@RequestBody FileVO params) 

四、结果说明

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中修改；如果是单文件上传，无需手动修改；可以参考示例代码

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

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

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

八、访问

8.1、直接使用swagger自带ui

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

8.2、使用三方ui

http://ip:port/doc.html

8.3、使用Yapi

http://172.16.2.164:300