Swagger使用注意事项-java

Posted

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了Swagger使用注意事项-java相关的知识,希望对你有一定的参考价值。

使用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头中

Swagger使用注意事项-java_ci


5.2、请求体中

Swagger使用注意事项-java_java_02

六、参考示例

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

Swagger使用注意事项-java_范型_03

8.2、使用三方ui

http://ip:port/doc.html

Swagger使用注意事项-java_ci_04

8.3、使用Yapi

http://172.16.2.164:300

Swagger使用注意事项-java_范型_05

以上是关于Swagger使用注意事项-java的主要内容,如果未能解决你的问题,请参考以下文章

swagger2的常用注解,传递参数的注意使用方法

Magento REST API详细信息或swagger doc

Swagger初学习笔记

Java中MongoDB返回ObjectId的差异

swagger3与swagger2区别

swagger-ui及swagger用法