/tags/springdoc/ Recent content in springdoc on Hugo -- gohugo.io en Fri, 10 Apr 2026 14:00:00 +0800 /posts/openapi-31-upgrade/ Fri, 10 Apr 2026 14:00:00 +0800 /posts/openapi-31-upgrade/ 📦 本文基于的完整项目源码：https://github.com/meirongdev/shop 🏷️ 当前文章对应的代码版本：openapi_3_1_upgrade 背景 我们的电商平台自启动以来，一直使用 OpenAPI 3.0.x 作为 API 文档规范。近期在整理 SpringDoc 2.8.9 和 JSON Schema 2020-12 工具链时，我顺手验证了一次 OpenAPI 3.1 升级的可行性，最后决定先在项目里试着切过去。 就这次实践看，升级过程主要是一行配置，没有涉及 Java 代码改动。下面更像是一份升级笔记：记录我为什么做这件事、哪些收益比较直接，以及哪些兼容性边界要先确认。 OpenAPI 3.1 的核心变化 OpenAPI 3.1 于 2021 年底发布（官方发布公告），虽然看起来只是小版本号 +1，但它底层做了一个根本性的改变：全面对齐 JSON Schema Draft 2020-12（JSON Schema 2020-12 规范）。 这不只是"换了一个标准"，更像是把 OpenAPI Schema 往 JSON Schema 工具链上靠近了一步。 变化一：nullable 语义重构 OpenAPI 3.0 的写法： { "type": "string", "nullable": true } 这是一个 OpenAPI 自定义扩展字段。JSON Schema 标准中不存在 nullable，这意味着： 标准 JSON Schema 校验器不认识它 代码生成器需要专门处理 OpenAPI 特有的逻辑 与 JSON Schema 生态工具链不互通 OpenAPI 3. /posts/openapi-aggregation-in-microservice-architecture/ Fri, 10 Apr 2026 10:00:00 +0800 /posts/openapi-aggregation-in-microservice-architecture/ 📦 本文基于的完整项目源码：https://github.com/meirongdev/shop 🏷️ 当前文章对应的代码版本：main 背景 在一个典型的微服务架构中，每个服务都独立维护自己的 API 文档。随着服务数量增长，前端开发者和第三方集成方常常面临一个痛点： 我需要去哪里找某个接口的文档？ 传统的解决方案是让开发者记住每个服务的地址，或者维护一个手动的聚合页面。但这些方案都存在明显的问题：容易过时、维护成本高、无法与 CI/CD 集成。 本文以一个云原生电商平台的实际案例，记录我们当前如何通过 Spring Cloud Gateway MVC + SpringDoc 维护一套相对省事的 OpenAPI 聚合方案。 架构概览 我们的平台采用 Gateway + Thin BFF + Domain Service 三层架构： Client └→ api-gateway:8080 (Spring Cloud Gateway MVC, JWT validation, rate limiting) ├→ /auth/** → auth-server ├→ /buyer/** → buyer-portal (Kotlin + Thymeleaf SSR) ├→ /seller/** → seller-app (KMP WASM SPA) ├→ /api/buyer/** → buyer-bff (aggregates domain services) ├→ /api/seller/** → seller-bff (aggregates domain services) ├→ /api/loyalty/** → loyalty-service ├→ /api/activity/** → activity-service ├→ /api/webhook/** → webhook-service └→ /api/subscription/** → subscription-service 共包含：