Spring Doc 胸弟你好香啊

纸仓
1,002 阅读4分钟

前言

你还在为写API文档而头秃吗?

你还在为更新文档而熬夜吗?

你还在为文档不同步而焦虑吗?

胸弟们，不用再苦恼了。今天这款革命性产品 Spring Doc 将彻底改变您的文档编写体验!

现在打开电脑，立即集成，还能获得限时优惠。

快快行动吧，机不可失，时不再来。

image.png

1. Spring Doc 你的API文档秘密武器!

你们的API文档还在原地踏步吗？今天为你带来 Spring Doc。它将彻底改变您的文档编写体验。让我们来看看它的三大杀手锏：

自动生成功能：您还在为手动更新文档而烦恼吗？Spring Doc 比您的贤内助（如果有）还要勤快哦。它24小时不间断工作，只要您动一动手指改代码，文档就自动更新啦。集成它，集成它，集成它。

Swagger UI集成：您还在为丑陋的接口文档掉粉吗？Spring Doc 带来的 Swagger UI 简直就是美颜神器（bushi）啊。保证让您的文档颜值爆表，在线文档界横着走，隔壁项目看了都说好。

OpenAPI 3.0支持: 您的API还在穿着老气横秋的大裤衩吗？快来试试 Spring Doc 的OpenAPI 3.0。让您的API穿上最新潮的皮肤，走在技术圈的最前沿。保证您一出场就是全场焦点。

202410311827516.png

重点来啦！集成Spring Doc不需要1天，不需要1小时，只要5分钟！没错，就是这么快。心动不如行动，快拿起您的键盘开始coding吧。不要再犹豫了，Spring Doc -- 您的 API 文档必备神器~

2. 那么哪里能教我集成呢？

image.png

别急，老司机带你飞~

  1. 先给它一个温暖的家(增加依赖):
<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-ui</artifactId>
	<version>1.8.0</version>
</dependency>
  1. 给它布置一个温馨的小窝(配置):
@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI openAPI() {
        // 省略一大堆代码...
        // 反正就是一顿骚操作
    }
}

开玩笑的，这个才是

@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI openAPI() {
        Info info = new Info()
                .title("Ext APIs")
                .description("Ext")
                .version("1.0.0");
        // 返回信息
        return new OpenAPI()
                // .openapi("3.0.1") // Open API 3.0.1(默认)
                .info(info);
    }
}

image.png

  1. 开始使用这个小可爱:
@RestController
@Tag(name = "用户订阅计划")
@RequestMapping("/user/subscription")
public class SubscriptionController {
    @Operation(summary = "订阅更新", description = "如果当前订阅是取消状态，且产品价格ID相同，则恢复<br>其他情况则返回跳转收银的URL")
    @PutMapping("update")
    public Result<SubscriptionUpdateResponse> update(
        @Parameter(hidden = true) @TokenParser CurrentUser user,
        @RequestBody @Valid SubscriptionUpdateForm form) {
        // 这里省略一万字...
    }
}

看到没？就是这么简单。

3. 用得比较多的注解就3个，还要啥自行车

  • @Tag：给你的接口贴标签，就像给你的小可爱起外号一样~
  • @Operation：描述你的接口是干啥的，就像介绍你的技能一样666
  • @Schema：给你的实体类化个妆，让它更有说服力

4. 骚操作集锦

image.png

统一配置鉴权：一次配置，到处使用，简直不要太爽。

@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI openAPI() {
        Info info = new Info()
                .title("Felo Search Ext APIs")
                .description("Felo Search Ext")
                .version("1.0.0");

        SecurityScheme securityScheme = new SecurityScheme()
                .name("Authorization")
                .type(SecurityScheme.Type.APIKEY)
                .description("Token")
                .in(SecurityScheme.In.HEADER);

        // 返回信息
        return new OpenAPI()
                .info(info)
                .components(new Components().addSecuritySchemes("authScheme", securityScheme)) // 添加鉴权组件
                .security(ImmutableList.of(new SecurityRequirement().addList("authScheme")));
    }
}

配置服务端地址：让你的请求知道该往哪儿跑~

@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI openAPI() {
        Info info = new Info()
                .title("Felo Search Ext APIs")
                .description("Felo Search Ext")
                .version("1.0.0");

        SecurityScheme securityScheme = new SecurityScheme()
                .name("Authorization")
                .type(SecurityScheme.Type.APIKEY)
                .description("Token")
                .in(SecurityScheme.In.HEADER);

        // 返回信息
        return new OpenAPI()
                .info(info)
                .servers(ImmutableList.of(
                        new Server().url("http://localhost:11001/"),
                        new Server().url("https://api-ext-dev.felo.ai/")))
                .components(new Components().addSecuritySchemes("authScheme", securityScheme)) // 添加鉴权组件
                .security(ImmutableList.of(new SecurityRequirement().addList("authScheme")));
    }
}

接口分组：内部接口外部接口分开展示，就像把你的小秘密和大实话分开放一样~

@Bean
public GroupedOpenApi rpc() {
    return GroupedOpenApi.builder()
            .group("rpc")
            .pathsToMatch("/rpc/**")
            .build();
}

@Bean
public GroupedOpenApi http() {
    return GroupedOpenApi.builder()
            .group("http")
            .pathsToMatch("/web/**")
            .build();
}

配置下划线风格：让你的接口文档看起来更有格调。

@Bean
@ConditionalOnProperty(name = "springdoc.api-docs.enabled", havingValue = "true", matchIfMissing = true)
public ModelResolver modelResolver(ObjectMapper objectMapper, SpringDocConfigProperties properties) {
    // ObjectMapper 通过Spring容器注入，这个对象读取了spring.jackson.property-naming-strategy配置
    return new ModelResolver(objectMapper).openapi31(properties.isOpenapi31());
}

总结

Spring Doc就是这么6，用了它你的API文档就会变得又香又甜，简直就是开发界的小甜甜。

image.png

还在等什么？快去试试吧！保证让你爽到飞起！

avatar
文章
阅读
粉丝