跳到主要内容
版本：3.9.x

OpenAPI 转换器参考

ADC 可以通过 adc convert openapi 命令将 OpenAPI v3.0 规范转换为 ADC 配置。本文档提供了支持的扩展/自定义属性的参考，用于配置 API7 企业版特有功能，如路由、插件和标签。

ADC OpenAPI 扩展在规范的以下级别受支持：

  • 根级别：API 规范的根级别。根级别的属性应用于整个服务。
  • 路径级别：规范中的路径部分。路径级别的属性应用于特定路由。
  • 操作级别：路径部分中的每个 HTTP 方法。操作级别的属性应用于路由的特定 HTTP 方法。
  • 服务器级别：根、路径或操作级别的服务器部分。服务器级别的属性应用于上游。

支持的扩展字段​

支持的级别
根级别：在 OAS 文档的根级别
路径级别：在每个路径对象上
操作级别：在每个路径的每个 HTTP 方法对象上
服务器级别：在服务器字段的每个条目上，支持根、路径和操作级别
字段级别描述
x-adc-name根级别覆盖生成的主服务的名称
操作级别覆盖生成的路由的名称
x-adc-labels根级别向指定级别添加标签字段。支持字符串和字符串数组格式。
路径级别
操作级别
x-adc-plugins根级别向指定级别添加插件字段。它是一个包含一个或多个插件的对象。
路径级别路径级别和操作级别的插件对象将导致服务被拆分，即包含插件的子级别将被包含在一个新服务中。
操作级别
x-adc-plugin-[插件名称]根级别这将与 x-adc-plugins 保持一致。但是，使用此格式配置的插件将覆盖 x-adc-plugins 中同名的插件。
路径级别
操作级别
x-adc-service-defaults根级别它支持在不同级别设置/覆盖服务中的参数。子级别上的此字段将导致服务被拆分。
路径级别
操作级别
x-adc-upstream-defaults根级别它支持在不同级别设置/覆盖上游中的参数。子级别上的此字段将导致服务被拆分。
路径级别
操作级别
x-adc-upstream-node-defaults根级别 - 服务器级别

它支持在不同级别设置/覆盖上游节点中的参数。子级别上的服务器字段将导致服务被拆分。

servers:
- url: "https://httpbin.org"
    x-adc-upstream-node-defaults:
    priority: 100
- url: "http://httpbin.org"
    x-adc-upstream-node-defaults:
    priority: 100
路径级别 - 服务器级别
操作级别 - 服务器级别
x-adc-route-defaults根级别它支持在不同级别设置/覆盖路由中的参数。子级别上的此字段将导致服务被拆分。
路径级别
操作级别

扩展字段处理逻辑​

x-adc-plugins 和 x-adc-plugin-[插件名称]​

它们可以在所有三个主要级别设置：根级别、路径级别和操作级别。

在同一级别同时设置 x-adc-plugins 和 x-adc-plugin-[插件名称]​

  1. 对于不同名称的插件，它们的配置将被合并。
输入输出
x-adc-plugins:
  test-plugin1:
    key: value
x-adc-plugin-test-plugin2:
  key: value
plugins:
  test-plugin1:
    key: value
  test-plugin2:
    key: value
  1. 对于同名的插件，x-adc-plugin-[插件名称] 中的配置将覆盖 x-adc-plugins 中的配置。
输入输出
x-adc-plugins:
  test-plugin1:
    key: value
x-adc-plugin-test-plugin1:
  key1: value1
plugins:
  test-plugin1:
    key1: value1

在多个级别同时设置 x-adc-plugins 或 x-adc-plugin-[插件名称]​

  • 根级别的插件配置将被映射到导出的服务。

  • 路径级别和操作级别都将被映射到此服务包含的路由。

区别在于：

  • 路径级别上的插件将包含在该路径对应方法的所有路由上。
输入输出
...
paths:
  /anything:
    x-adc-plugin-test-plugin:
      key: value
    get: ...
    post: ...
...
services:
  - name: demo
    routes:
      - name: demo_anything_get
        uris: [/anything]
        methods: [GET]
        plugins:
          test-plugin:
            key: value
      - name: demo_anything_post
        uris: [/anything]
        methods: [POST]
        plugins:
          test-plugin:
            key: value
  • 操作级别上与路径级别同名的插件将覆盖路径级别上的插件。
输入输出
...
paths:
  /anything:
    x-adc-plugin-test-plugin:
      key: value
    get: ...
      x-adc-plugin-test-plugin:
        key1: value1
      x-adc-plugin-test-plugin2:
        key: value
    post: ...
...
services:
  - name: demo
    routes:
      - name: demo_anything_get
        uris: [/anything]
        methods: [GET]
        plugins:
          test-plugin:
            key1: value1
          test-plugin2:
            key: value
      - name: demo_anything_post
        uris: [/anything]
        methods: [POST]
        plugins:
          test-plugin:
            key: value

示例规范​

下面的示例规范展示了如何使用这些扩展：

openapi: 3.0.0
info:
  title: httpbin API
  description: httpbin API for the API7 Enterprise Getting Started guides.
  version: 1.0.0
servers:
  - url: 'http://httpbin.org:80'
x-adc-labels:
  server: production
  api: httpbin
x-adc-plugins:
  key-auth:
    _meta:
      disable: false
paths:
  /anything/*:
    get:
      summary: Returns anything that is passed into the request.
      x-adc-name: httpbin-anything
      x-adc-service-defaults:
        path_prefix: /api
      x-adc-upstream-defaults:
        timeout:
          connect: 10
          send: 10
          read: 10
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: string