1.前言
2.swagger接口文档
接口文档使用的主要是 swagger，早先的版本和现在的版本有很大的差别，如今主要是 swagger v3 版本。
(1) 系统后台启动之后，打开 http://localhost:8080/jeecg-boot/#/home 就可以看到全部的接口文档了。
(2) 编写接口
通过使用 @Tag 注解和 @Operation 注解，可以新建一个新的接口
1
2
3
4
5
6
7
8
9
10
| @RestController
@RequestMapping("/sys")
@Tag(name="用户登录")
@Slf4j
public class LoginController {
@Operation(summary = "登录接口")
@RequestMapping(value = "/login", method = RequestMethod.POST)
public Result<JSONObject> login(@RequestBody SysLoginModel sysLoginModel, HttpServletRequest request){
}
}
|
（3）主要注解
- @Operation Describes an operation or typically a HTTP method against a specific path.
- @Parameter Represents a single parameter in an OpenAPI Operation.
- @RequestBody Represents the body of the request in an Operation
- @ApiResponse Represents the response in an Operation
- @Tag Represents tags for an operation or for the OpenAPI definition.
- @Server Represents servers for an operation or for the OpenAPI definition.
- @Callback Describes a set of requests
- @Link Represents a possible design-time link for a response.
参考文章:
【1】.Jeecg-Boot 后台服务API接口文档 这是别人的接口文档说明
【2】.自动生成代码后 ,无法在接口文档里面查看到接口信息
【3】.swagger使用 1.启动system项目,访问路径：http://localhost:8080/jeecg-boot;2.获取验证码，按图操作，输入参数key的值，此处输入123，点击发送，获取验证码图片;3.登录,获取token;
【4】.Swagger 中的 @Operation 和 @ApiResponse 注解
【5】.Swagger 注解使用 这是 swagger 的版本：1.3.2
【6】.Swagger 3.0 使用指南 这里进行了依赖集成，注解说明等
【7】.SpringBoot集成Swagger3.0 这个比较详细
【8】.swagger添加注解后不显示接口信息问题 同样的还有可能是因为swagger配置类中扫描的包不对，例如下面这段代码中basePackage配置的路径不对导致的。
也就是说swagger不仅要扫描到controller及方法，还要扫描到实体类，标注了ApiModel注解的实体类。
3.Knife4j
jeecgboot 集成了 knife4j 进行文档接口的使用。
（1）依赖
1
2
3
4
5
| <dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.4.0</version>
</dependency>
|
（2）配置
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
|
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: com.xiaominfo.knife4j.demo.web
knife4j:
enable: true
setting:
language: zh_cn
|
（3）代码
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
37
38
39
40
41
| @Configuration
public class Swagger3Config implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
@Bean
public GroupedOpenApi swaggerOpenApi() {
return GroupedOpenApi.builder()
.group("default")
.packagesToScan("org.jeecg","com.dji")
.packagesToExclude("org.jeecg.modules.drag", "org.jeecg.modules.online", "org.jeecg.modules.jmreport")
.addOpenApiMethodFilter(method -> method.isAnnotationPresent(Operation.class))
.build();
}
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("JeecgBoot 后台服务API接口文档")
.version("1.0")
.contact(new Contact().name("北京国炬信息技术有限公司").url("www.jeccg.com").email("jeecgos@163.com"))
.description( "后台API接口")
.termsOfService("NO terms of service")
.license(new License().name("Apache 2.0").url("http://www.apache.org/licenses/LICENSE-2.0.html"))
);
}
}
|
（4）调试
调试的时候，默认的接口地址是不带 server.servlet.context-path ,比如调试地址显示 ：/drone/devices/test，实际上应该是 /hjkj/drone/devices/test。或者增加配置，启用 host 。
1
2
3
4
5
6
7
8
| knife4j:
enable: true
setting:
language: zh_cn
enable-host: true
enable-host-text: http://localhost:${server.port}/hjkj
|
（5）用户授权
有些接口需要用户认证的时候，需要增加全局参数，在接口页面 -> 文档管理 -> 全局参数设置，添加认证的 jwt token, 然后刷新接口就可以了，这样就可以在调试的时候自动加入 参数信息了，实现了用户接口授权。
参考文章:
【1】.快速开始 这是官方使用教程
【2】.knife4j的简单使用(二)—配置多个扫描包
【3】.3.17 自定义Host 增加了 host 说明
【4】.3.5 访问权限控制 系统部署生产环境时,我们想屏蔽Swagger的文档功能,不管是接口或者html文档,通常我们有时候需要生产环境部署后,又需要Swagger的文档调试功能,辅助开发者调试,但是存在安全隐患,没有对Swagger的资源接口过滤,针对以上两种情况,Knife4j基于Servlet体系提供了过滤Filter功能,如果开发者使用Spring Boot开发框架进行开发的话,只需在application.properties或者application.yml配置文件中配置相关属性即可方便的解决上面的问题,不用删除Springfox-swagger的jar包或者删除相关代码等复杂的操作,提升开发体验.
【5】.gateway-nacos-knife4j整合加访问权限控制(详细教程适合新手入门)
