OpenAPI 向下转换
openapi-down-convert 是将 API 定义文档从
OpenAPI 3.1改为OpenAPI 3.0.
- OpenAPI 规格( OAS) 3.1.0 释放 说明从美洲组织3.0到美洲组织3.1的变动.
- 见 从 OpenAPI 3.0 移动到 3.1.0 因为往另一个方向走 这个工具帮助"Undo"一些这些转变.
3⁄4 ̄ ̧漯B:这不是一个完全有力的工具。 它只做最起码的必要工作
美洲组织 3.1 API文件,以支持工具,如 openapi-generator
并不支持美洲组织第3.1条。 它只支持美洲国家组织3.1的特点,即
Apiture APIs使用. 星洲网.
3⁄4 ̄ ̧漯B: 向下转换会导致忠诚的丧失。 一些 API 信息 丢失.
安装和概要
该工具由Node.js执行.
国家防范机制
npm i @apiture/openapi-down-convert
import { Converter, ConverterOptions } from './converter';
const options : ConverterOptions = { verbose: false,
deleteExampleWithId: true,
allOfTransform: false };
const converter = new Converter(oas31Document, options);
try {
const oas30Document = converter.convert();
...
}
} catch (ex) {
// handle the exception
}
由于转换器的用例是在建造管道和CLI的使用中,
此操作是同步的, 不使用 async/await/Promises。 。 。 .
QQ 命令行
安装 :
npm i -g @apiture/openapi-down-convert
然后使用 :
openapi-down-convert --input openapi-3.1.yaml --output openapi-3.0.yaml
命令行选项 :
Usage: openapi-down-convert [options]
Options:
-i, --input <input-file> A OpenAPI 3.1 file name. Defaults to "openapi.yaml"
-o, --output <output-file> The output file, defaults to stdout if omitted
-a, --allOf If set, convert complex $ref in JSON schemas to allOf
--authorizationUrl <authorizationUrl> The authorizationUrl for openIdConnect -> oauth2 transformation
--tokenUrl <tokenUrl> The tokenUrl for openIdConnect -> oauth2 transformation
-d, --delete-examples-with-id If set, delete any JSON Schema examples that have an `id` property
--oidc-to-oath2 <scopes> Convert openIdConnect security to oath2.
--convertJsonComments If used, convert `$comment` in JSON schemas
to `x-comment`. If omitted, delete
all `$comment` in JSON schemas.
(Use `--verbose` to log deletion
to stdout)
-s, --scopes <scopes> If set, this JSON/YAML file describes the OpenID scopes.
This is an alias for --oidc-to-oath2
-v, --verbose Verbose output
-V, --version output the version number
-h, --help display help for command
动词模式记录标准出错输出流的所有变化.
工具在成功时返回 0 状态代码或非 0 状态代码
如果它找到无法下调的构造,例如
使用 contentMediaType: application/octet-stream 带有 format
其他 binary或者如果一个计划 contentEncoding: base64
并拥有 format 还没有 base64。 。 。 .
该工具只支持基于本地文件的文档,而不是URL. 下载要转换的文件 :
openapi-down-convert --input <(curl -s https://my.host/path/openapi-3.1.yaml) \
--output openapi-3.0.yaml
OpenAPI 规格转换
以下是该工具执行的转换列表 :
qq openapi 声明
变动 openapi: 3.1.x 改为 openapi: 3.0.3
⤓ openIdConnect 安全定义
替换 openIdConnect 带有 oauth2 安保要求
它们足够接近,就代码生成而言(例如: openapi-generator(中文(简体) )
关心 - 它只是意味着 Authorization: header 必须有有效的符号.
说明: 只有在 --oidc-to-oauth2 选项
(或作别名, --scopes提供.
使用其他选项指定 authorizationUrl 财务报告和审定财务报表 tokenUrl 联 合 国
oauth2 安全定义.
TODO: 获取 OpenIdConnect 连接信息并提取授权和 其符号 URL .
accessToken:
type: openIdConnect
description: ...
openIdConnectUrl: 'https://auth.apiture.com/openidConnectDiscovery'
变成类似的东西:
accessToken:
type: oauth2
description: "OpenIDConnect authorization code flow via https://auth.apiture.com/openidConnectDiscovery"
flows:
authorizationCode:
authorizationUrl: <authorizationUrl option>
tokenUrl: <tokenUrl option>
scopes:
scope1: Allow the application to access your personal profile data.
scope2: Allow the application to send email on your behalf.
scope3: >-
TODO: describe the 'scope3' scope.
scope4: >-
TODO: describe the 'scope4' scope.
工具扫描所有 security 在所有操作中创建对象
使用范围列表。 范围说明应为:
应在 scopes.yaml文件为简单 scopeName: scope description
配对 :
scope1: Allow the application to access your personal profile data.
scope2: Allow the application to send email on your behalf.
⤓ $ref 对象重写
对于所有包含 $ref 有兄弟姐妹的物体(description,其他
替换 $ref: 纯度为 allOf 。例如:
myProperty:
description: Blah blah
$ref: '#/components/schemas/MyArray'
改为:
mySchema:
description: Blah blah
allOf:
- $ref: '#/components/schemas/MyArray'
这也适用于参数或参数中使用的图案 requestBody 对象
和反应.
说明 此变换默认被禁用, 因为它会中断
openapi-generator 5.4 在引用的策略是数组的情况下.
它为此类案件生成打字符类型, 如
myProperty: Array | null;
model/Model.ts:26:23 - error TS2314: Generic type 'Array<T>' requires 1 type argument(s).
应该是
incompleteAccounts: Array<string> | null;
为了启用,使用 allOfTransform: true 选项 Converter 构造器
或 --allOf 命令行参数。 残疾时 $ref 相反
简化为 a JSON 参考。 。 。 .
其他(非JSON Schema) $ref 对象可以有 description 财务报告和审定财务报表 summary。 。 。 .
$ref 对于OAS 3.0中的非舍标对象,不能有 description 财务报告和审定财务报表
summary。 。 。 . openapi-down-convert 简单地删除 description 财务报告和审定财务报表
summary 生成有效的 JSON 参考
根据美洲组织3.0的要求。 (由此产生的 OpenAPI 将使用 description
输入 $ref 目标。 )
⤓ info.license.identifier
删除 info.license.identifier。 。 。 .
⤓ webhooks
删除 webhooks 对象,如果存在.
JSON Schema 相关变化
OAS 3. 0 使用较早的 JSON Schema 版本
(单位:千美元)JSON Schema 规格 Wright 第00号草案) (中文(简体) ). 工具转换 examples
在计程器到单 example。 。 。 .
作为一种特殊情况,如果 example 包含 id,这是
如果 --delete-examples-with-id CLI 选项已设定 .
这个地址 2081年光谱问题。 。 。 .
++ 转换 const 改为 enum
转换使用的 JSON Schema const 改为: enum 一个值。 举个例子
components:
schema:
version:
description: The API version.
type: string
const: '1.0.0'
变成
components:
schema:
version:
description: The API version.
type: string
enum:
- '1.0.0'
将类型数组转换为无效
如果一个计程器有一个完全由两个值组成的类型数组,并且其中之一
是字符串 'null',该类型转换为非核字符串项目,
财务报告和审定财务报表 nullable: true 增入诸法.
例如:
myResponse:
title: My Response
description: Response from an API operation
type: [ object, 'null' ]
allOf:
...
变成
myResponse:
title: My Response
description: Response from an API operation
type: object
nullable: true
allOf:
...
财务报告和审定财务报表
myResponse:
title: My Response
description: Response from an API operation
type: array
items:
type: [ 'string', 'null' ]
...
变成
myResponse:
title: My Response
description: Response from an API operation
type: array
items:
type: string
nullable: true
...
这种转换不会处理更复杂的 type 数组
情景,例如:
type: [ number, string, boolean, 'null']
为了支持这一点,需要使用 oneOf, (中文(简体) ),
但这并非小事 因为其他的图谋属性可能
有可能(properties, (中文(简体) ), allOf (例如)
(欢迎捐款。 )
删除 unevaluatedProperties
工具删除 unevaluatedProperties 值,稍后引入
jSON Schema的版本,
由于美洲组织3.0 JSON Schema草稿7不支持这一点
用于OAS 3.0.
myResponse:
title: My Response
description: Response from an API operation
type: object
unevaluatedProperties: false
allOf:
...
变成
myResponse:
title: My Response
description: Response from an API operation
type: object
allOf:
...
工具删除任何 $id 或者说 $schema 可能出现的关键字
里面的图案对象.
++ 转换 $comment 改为 x-comment
JSON Schema介绍 $comment (原始内容存档于2020-12-12). in schemas in 2020.
由于OAS 3.0使用JSON Schema Draft 4和一些工具
将旗下 $comment 由于无效,本工具将删除这些注释.
该工具的更早版本已转换 $comment 改为 x-comment
然而,其他工具不允许 $comment 可能不支持
x-comment 也一样.
使用 --convert-schema-comments CLI 选项或设置
convertSchemaComments 改为 true
输入 Converter 构造器选项
转换
$comment 改为 x-comment 而不是删除 $comment。 。 。 .
譬如说,
Problems:
title: Problems
description: Problem Items
type: array
maxItems: 1000
$comment: >-
The value 1000 here must match `maxItems` in the ProblemList schema.
items:
$ref: '#/components/schemas/apiProblem'
变成
Problems:
title: Problems
description: Problem Items
type: array
maxItems: 1000
x-comment: >-
The value 1000 here must match `maxItems` in the ProblemList schema.
items:
$ref: '#/components/schemas/apiProblem'
转换 contentEncoding: base64 改为 format: byte
JSON Schema 第7稿及以后使用 contentEncoding 指定
[非JSON字符串内容的编码]
(单位:千美元)https://json-schema.org/understand-json-schema/ reference/non json data 互联网档案馆的存檔,存档日期2013-12-22) (中文(简体) ).
草案4支持 format: byte 页:1 Base64 编码字符串.
此工具转换 type: string 计划如下:
| 美洲组织 3.1 计划a | 美洲组织 3.0 计划a |
|---|---|
type: string contentEncoding: base64 |
type: string format: byte |
type: string contentMediaType: 'application/octet-stream' |
type: string format: binary |
不支持的向下转换
目前,该工具不支持下列情况. 欢迎捐款!
openapi-down-convert不转换exclusiveMinimum财务报告和审定财务报表exclusiveMaximum, (中文(简体) ),unevaluatedProperties, (中文(简体) ),patternProperties, (中文(简体) ),propertyNamesjSON Schema 2020-12中的定义;JSON Schema Draft 7不支持这些内容 用于美洲组织3.0- 该工具只支持自成一体的文档. 它没有跟随或决心
外部
$ref文档嵌入源文档. - 请求机构和答复机构
content对象转换,例如 反转content: { 'application/octet-stream': {} }作为 说明 从 OpenAPI 3.0 移动到 3.1.0 - 其他转换
contentEncoding数值(7bit, (中文(简体) ),8bit, (中文(简体) ),binary, (中文(简体) ),quoted-printable, (中文(简体) ),base16, (中文(简体) ),base32(注:contentEncoding: base64由 转换为format: byte(如上所示。 ) - 转换
contentMediaType: 'type/subtype改为media: { type: 'type/subtype'}非JSON数据.