你好,这里是codetrend专栏“SpringCloud2023实战”。
本文主要简单介绍SpringCloud2023中进行接口文档管理,方便前后端开发和文档维护。文档管理工具基于开源的knife4j封装的openapi3。
OpenAPI 3.0(前身为Swagger)是一种RESTful API文档规范。OpenAPI 3.0规范是一种易于阅读和理解、跨平台和语言、提高协作效率、提供API管理和监控的RESTful API文档规范,提高了API设计和开发的效率、可重用性和互操作性。
有以下几个优点:
springdoc-openapi-starter-webmvc-ui
。knife4j-openapi3-jakarta-spring-boot-starter
快速集成到springboot 3项目,以及使用它提供的增强服务。<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<dependencies>
<!--其他省略-->
<!-- 引入openapi3接口文档支持 -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
</dependency>
</dependencies>
</project>
application.yml
,配置主要是 springdoc
下面的配置,以及 knife4j
下面的增强实现配置。spring.application.name: client1
# springdoc-openapi项目配置
springdoc:
swagger-ui:
path: /swagger-ui.html
tags-sorter: alpha
operations-sorter: alpha
api-docs:
path: /v3/api-docs
group-configs:
- group: 'default'
paths-to-match: '/**'
packages-to-scan: io.rainforest.banana.client1.web
# knife4j的增强配置,不需要增强可以不配
knife4j:
enable: true
setting:
language: zh_cn
basic:
enable: true
# Basic认证用户名
username: yulin
# Basic认证密码
password: 123yl.
knife4j.enable
控制的。package io.rainforest.banana.client1;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
import org.springframework.cloud.openfeign.EnableFeignClients;
@SpringBootApplication
@EnableDiscoveryClient
@EnableFeignClients
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
http://localhost:10101/client1/swagger-ui.html
,输入账号密码 yulin/123yl. 就可以访问到最新的接口文档。package io.rainforest.banana.client1.web.demo;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("body")
@Tag(name = "body参数")
public class BodyController {
@Operation(summary = "普通body请求")
@PostMapping("/body")
public ResponseEntity<String> body(String fileResp){
return ResponseEntity.ok(fileResp);
}
@Operation(summary = "普通body请求+Param+Header+Path")
@Parameters({
@Parameter(name = "id",description = "文件id",in = ParameterIn.PATH),
@Parameter(name = "token",description = "请求token",required = true,in = ParameterIn.HEADER),
@Parameter(name = "name",description = "文件名称",required = true,in=ParameterIn.QUERY)
})
@PostMapping("/bodyParamHeaderPath/{id}")
public ResponseEntity<String> bodyParamHeaderPath(@PathVariable("id") String id, @RequestHeader("token") String token, @RequestParam("name")String name, @RequestBody String fileResp){
return ResponseEntity.ok(fileResp+""+",receiveName:"+name+",token:"+token+",pathID:"+id);
}
}
具体的openapi3
注释和文档可以查看官方文档。和swagger的语法结构类似,但是注解名称和属性都还是差异很大的。
以下是一个简单的Swagger2和OpenAPI3的注解映射关系,可以参考:
@Api → @Tag
@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
@ApiParam → @Parameter
@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")
来自一线全栈程序员nine的探索与实践,持续迭代中。
欢迎关注或者点个小红心~
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。