swagger外部文档

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: petstore
  description: The Petstore API
spec:
  type: openapi
  lifecycle: production
  owner: petstore@example.com
  definition:
    $text: https://petstore.swagger.io/v2/swagger.json

嵌入openapi文档

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: artist-api
  description: Retrieve artist details
spec:
  type: openapi
  lifecycle: production
  owner: artist-relations-team
  system: artist-engagement-portal
  definition: |
    openapi: "3.0.0"
    info:
      version: 1.0.0
      title: Artist API
      license:
        name: MIT
    servers:
      - url: http://artist.spotify.net/v1
    paths:
      /artists:
        get:
          summary: List all artists
    ...

占位符$text解释当前仓库相对路径

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: pet-store-api
spec:
  type: openapi
  lifecycle: experimental
  owner: guests
  system: user-system
  # 使用 $text 占位符和相对路径引用同一仓库内的 OpenAPI 文件
  # 路径相对于 catalog-info.yaml 文件的位置
  definition:
    $text: ./src/main/resources/petstore.yaml

openapi和protobuf的对比

简单来说：OpenAPI 是 API 的描述规范和文档标准，而 Protobuf 是一种高效的数据序列化协议和接口定义语言。 它们常常结合使用，但核心目标不同。

以下是详细的对比：

核心关系与如何选择

1. 不是“二选一”，而是“如何搭配”：

   • 你可以用 Protobuf 定义内部微服务接口（通过 gRPC），然后用 OpenAPI 定义对外的 RESTful API 网关。网关负责将外部 REST 调用转换为内部的 gRPC 调用。
   • 也有工具（如 grpc-gateway）能从一个 .proto 文件同时生成 gRPC 服务代码和对应的 OpenAPI 规范，实现“一套定义，两种暴露”。

2. 选择建议：

   • 选择 OpenAPI 当：
     • 你的 API 主要给浏览器、移动 App 或第三方开发者调用。
     • API 文档和易用性是首要考虑。
     • 你需要与现有的、基于 HTTP/JSON 的生态系统（如大多数云服务、前端框架）集成。
   • 选择 Protobuf (gRPC) 当：
     • 你的系统是内部微服务架构，服务间需要高性能、低延迟的通信。
     • 强类型安全和接口契约对团队协作至关重要。
     • 你需要支持流式通信（如 gRPC 的流）。
     • 网络带宽和性能是瓶颈。

总结

在现代云原生架构中，两者通常协同工作：用 Protobuf/gRPC 构建高效、稳定的后端服务网格，然后用基于 OpenAPI 的 API 网关作为统一、安全的对外入口。