SpringBoot之接口文档

标签：无分类：未分类创建时间：2024-07-11 04:32:24 更新时间：2025-01-17 10:39:22

1.前言

2.swagger接口文档

接口文档使用的主要是 swagger，早先的版本和现在的版本有很大的差别，如今主要是 swagger v3 版本。
(1) 系统后台启动之后，打开 http://localhost:8080/jeecg-boot/#/home 就可以看到全部的接口文档了。

(2) 编写接口
通过使用 @Tag 注解和 @Operation 注解，可以新建一个新的接口

@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）依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

（2）配置

# 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: com.xiaominfo.knife4j.demo.web
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

（3）代码

@Configuration
public class Swagger3Config implements WebMvcConfigurer {
        /**
     *
     * 显示swagger-ui.html文档展示页，还必须注入swagger资源：
     *
     * @param registry
     */
    @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")
                // 加了Operation注解的方法，才生成接口文档
                .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 。

knife4j:
  enable: true
  setting:
    language: zh_cn
    # 是否启用Host
    enable-host: true
    # 启用Host后地址，例如：http://192.168.0.111:8080
    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整合加访问权限控制(详细教程适合新手入门)

往期推荐

文章目录

微信公众号

广告位

诚心邀请广大金主爸爸洽谈合作

每日一省

isNaN 和 Number.isNaN 函数的区别？

1.函数 isNaN 接收参数后，会尝试将这个参数转换为数值，任何不能被转换为数值的的值都会返回 true，因此非数字值传入也会返回 true ，会影响 NaN 的判断。

2.函数 Number.isNaN 会首先判断传入参数是否为数字，如果是数字再继续判断是否为 NaN ，不会进行数据类型的转换，这种方法对于 NaN 的判断更为准确。

每日二省

为什么0.1+0.2 ! == 0.3，如何让其相等?

一个直接的解决方法就是设置一个误差范围，通常称为“机器精度”。对JavaScript来说，这个值通常为2-52，在ES6中，提供了Number.EPSILON属性，而它的值就是2-52，只要判断0.1+0.2-0.3是否小于Number.EPSILON，如果小于，就可以判断为0.1+0.2 ===0.3。

每日三省

== 操作符的强制类型转换规则？

1.首先会判断两者类型是否**相同，**相同的话就比较两者的大小。

2.类型不相同的话，就会进行类型转换。

3.会先判断是否在对比 null 和 undefined，是的话就会返回 true。

4.判断两者类型是否为 string 和 number，是的话就会将字符串转换为 number。

5.判断其中一方是否为 boolean，是的话就会把 boolean 转为 number 再进行判断。

6.判断其中一方是否为 object 且另一方为 string、number 或者 symbol，是的话就会把 object 转为原始类型再进行判断。

每日英语

Happiness is time precipitation, smile is the lonely sad.

幸福是年华的沉淀，微笑是寂寞的悲伤。