当前位置:网站首页>如何形成规范的接口文档
如何形成规范的接口文档
2022-07-05 20:14:00 【幼儿园里的山大王】
一、需求
前后端对接时,后端需要提供一个规范的,或者说前端能够看明白的接口文档是一个非常重要的事。那如何使用注解快速、简单的形成接口文档呢。
二、Swagger2切换knife4j的使用
1、在pom.xml中增加knife4j的相关依赖
<!--整合Knife4j-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.4</version>
</dependency>
2、在Swagger2Config中增加一个@EnableKnife4j注解,该注解可以开启knife4j的增强功能
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Config {
@Bean
public Docket ssoFront() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("接口所在的包路径"))
.paths(PathSelectors.any())
.build().groupName("分组名");
}
@Bean
public Docket ssoAdmin() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.user.controller.admin"))
.paths(PathSelectors.any())
.build().groupName("sso-admin");
}
@Bean
public Docket member() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.user.controller.member"))
.paths(PathSelectors.any())
.build().groupName("member-service");
}
@Bean
public Docket system() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.user.controller.system"))
.paths(PathSelectors.any())
.build().groupName("system-service");
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("某某模块文档")
.description("用户模块API文档")
.contact(new Contact("作者", null, null))
.version("v1")
.build();
}
}
3、运行我们的SpringBoot应用,访问API文档地址即可查看:http://localhost:端口号/doc.html
三、功能特点
对比swagger来说
1、 返回结果集支持折叠,方便查看
2、 请求参数有JSON校验功能
3、 knife4j支持导出离线文档,方便发送给别人,支持Markdown格式;直接选择文档管理->离线文档
功能,然后选择下载Markdown
即可
三、根据不同的请求方式使用不同的注解形成接口文档
一、swagger注解应用
1、在控制层当中,可以在controller上使用注解@Api(tags = "接口服务名")标注这个控制器的功能。
2、在具体接口上可以使用注解@ApiOperation(value = "邮箱模糊匹配查询服务接口",notes = "对邮箱进行模糊匹配")对这个接口进行命名以及对这个接口得到功能进行描述
二、@ApiOperation与Get请求注解配合使用
1、使用注解@RequestParam(value = "传入邮箱",required = false),注意name和value不能共存,不然无法生成接口文档。swagger会自动识别这个注解生成对应文档
Get请求数据类型为:
2、使用 @PathVariable(value = "传入邮箱",required = false)也一样。区别只是请求类型不同一个是query,一个是path
3、不需要@ApiImplicitParam(name = "邮箱模糊匹配查询", value = "likeEmail", required = false)这个注解,否者会出现两个一样的参数。
三、@ApiOperation与Post请求注解配合使用
1、使用@RequestBody注解请求参数实体。实体里面在类上头加入
@ApiModel(value = "某某请求报文",description = "某某请求报文,父类是",parent = 类.class)
2、在属性中加入
@ApiModelProperty(value="某某属性",required = true)
@ApiOperation("某某请求报文")
@PostMapping("edit")
public JsonResult edit(@RequestBody EditDTO dto) {
return
}
swagger会自动扫描实体类里面加了注解的数据形成接口文档
3、post请求数据格式
四、所有返回报文如果带有返回参数的需要明确返回参数
只有带了明确返回报文,且报文里 类名@ApiModel和属性@ApiModelProperty也用了注解,那么返回报文的数据类型也会出现在接口文档中。
下方还会出现相应示例、
注:注解与请求类型的配合使用可参考下面文章
边栏推荐
- 死信队列入门(两个消费者,一个生产者)
- 随机数生成的四种方法|Random|Math|ThreadLocalRandom|SecurityRandom
- 淺淺的談一下ThreadLocalInsecureRandom
- 怎么挑选好的外盘平台,安全正规的?
- Hong Kong stocks will welcome the "best ten yuan store". Can famous creative products break through through the IPO?
- 【数字IC验证快速入门】8、数字IC中的典型电路及其对应的Verilog描述方法
- Bzoj 3747 poi2015 kinoman segment tree
- Leetcode brush questions: binary tree 11 (balanced binary tree)
- 【数字IC验证快速入门】2、通过一个SoC项目实例,了解SoC的架构,初探数字系统设计流程
- A way to calculate LNX
猜你喜欢
leetcode刷题:二叉树12(二叉树的所有路径)
Leetcode brush question: binary tree 14 (sum of left leaves)
Elk distributed log analysis system deployment (Huawei cloud)
Convolution free backbone network: Pyramid transformer to improve the accuracy of target detection / segmentation and other tasks (with source code)
[quick start of Digital IC Verification] 3. Introduction to the whole process of Digital IC Design
leetcode刷题:二叉树17(从中序与后序遍历序列构造二叉树)
Go language | 03 array, pointer, slice usage
S7-200smart uses V90 Modbus communication control library to control the specific methods and steps of V90 servo
死信队列入门(两个消费者,一个生产者)
图嵌入Graph embedding学习笔记
随机推荐
Let's talk about threadlocalinsecurerandom
About the priority of Bram IP reset
Oracle-表空间管理
港股将迎“最牛十元店“,名创优品能借IPO突围?
Leetcode brush question: binary tree 13 (the same tree)
ROS2专题【01】:win10上安装ROS2
Go language | 02 for loop and the use of common functions
走入并行的世界
C langue OJ obtenir PE, ACM démarrer OJ
Leetcode brush question: binary tree 14 (sum of left leaves)
【数字IC验证快速入门】2、通过一个SoC项目实例,了解SoC的架构,初探数字系统设计流程
leetcode刷题:二叉树11(平衡二叉树)
After 95, Alibaba P7 published the payroll: it's really fragrant to make up this
图嵌入Graph embedding学习笔记
解决Thinkphp框架应用目录下数据库配置信息修改后依然按默认方式连接
Hong Kong stocks will welcome the "best ten yuan store". Can famous creative products break through through the IPO?
leetcode刷题:二叉树17(从中序与后序遍历序列构造二叉树)
Unity editor extended UI control
Cocos2d-x项目总结中的一些遇到的问题
js方法传Long类型id值时会出现精确损失