npm 包 @microsoft.azure/oai2-to-oai3 使用教程

介绍

OpenAPI 规范是当前非常流行的 RESTful API 的规范，大多数公司的 Web API 文档都是使用 OpenAPI 规范来定义的。在这个规范中，有两个版本：OpenAPI 2.0 和 OpenAPI 3.0。OpenAPI 3.0 又比 OpenAPI 2.0 更加严格、更加标准化，而且对于 JSON Schema 的支持也得到了很大的改进。

然而，由于历史原因，很多公司的 Web API 已经使用了 OpenAPI 2.0 规范来定义，并且已经发布了相应的文档。因此，当我们需要将这些 Web API 升级到 OpenAPI 3.0 规范时，需要手动地将 OpenAPI 2.0 规范转换成 OpenAPI 3.0 规范。手动转换会非常繁琐和费时，因此我们可以使用 npm 包 @microsoft.azure/oai2-to-oai3 来进行转换。

安装

通过 npm 安装

npm i -g @microsoft.azure/oai2-to-oai3

通过源码安装

git clone https://github.com/microsoft/oai-ts-to-oai.git
cd oai-ts-to-oai
npm install
npm run build

使用

命令行

我们可以使用以下命令行将 OpenAPI 2.0 规范转换成 OpenAPI 3.0 规范：

oai2-to-oai3 -f openapi2-file.yaml -o openapi3-file.yaml

JavaScript

我们也可以在 JavaScript 代码中使用 @microsoft.azure/oai2-to-oai3 包：

const OpenAPI2ToOpenAPI3 = require('@microsoft.azure/oai2-to-oai3')

const openapi2 = {
  swagger: '2.0',
  info: {...},
  paths: {...},
  ...
}

const openapi3 = OpenAPI2ToOpenAPI3(openapi2)

示例

OpenAPI 2.0 规范文件

swagger: '2.0'
info:
  title: Sample API
  description: This is a sample API definition for OpenAPI 2.0.
  version: '1.0'
basePath: /api
schemes:
  - https
paths:
  /user:
    get:
      tags:
        - User
      summary: Retrieve a list of users.
      description: This endpoint retrieves a list of users.
      produces:
        - application/json
      responses:
        '200':
          description: A list of users.
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
      security:
        - apiKey: []
    post:
      tags:
        - User
      summary: Create a new user.
      description: This endpoint creates a new user.
      produces:
        - application/json
      parameters:
        - name: user
          in: body
          required: true
          schema:
            $ref: '#/definitions/User'
      responses:
        '201':
          description: The newly created user.
          schema:
            $ref: '#/definitions/User'
      security:
        - apiKey: []
definitions:
  User:
    type: object
    properties:
      username:
        type: string
      password:
        type: string
      email:
        type: string

OpenAPI 3.0 规范文件

openapi: 3.0.0
info:
  title: Sample API
  description: This is a sample API definition for OpenAPI 3.0.
  version: '1.0'
servers:
  - url: https://api.example.com/v1
basePath: /api
schemes:
  - https
paths:
  /user:
    get:
      tags:
        - User
      summary: Retrieve a list of users.
      description: This endpoint retrieves a list of users.
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
      security:
        - apiKey: []
    post:
      tags:
        - User
      summary: Create a new user.
      description: This endpoint creates a new user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: The newly created user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      security:
        - apiKey: []
components:
  schemas:
    User:
      type: object
      properties:
        username:
          type: string
        password:
          type: string
        email:
          type: string

总结

@microsoft.azure/oai2-to-oai3 包可以帮助我们快速将 OpenAPI 2.0 规范转换成 OpenAPI 3.0 规范。我们可以通过命令行或者 JavaScript 代码来使用它。本文介绍了如何安装和使用 @microsoft.azure/oai2-to-oai3 包，并提供了相应的示例代码。希望这篇文章能够帮助您更好地了解 OpenAPI 规范的转换和使用。

来源：JavaScript中文网 ，转载请注明来源 本文地址：https://www.javascriptcn.com/post/600673e0fb81d47349e53cd8