README

关于

openapi-gen 包提供了一种方便的方式来使用单个配置文件为 Laravel、Lumen 或 Dingo 创建 OpenApi 规范。它旨在用于轻量级微服务，并且可以被各种包解析以启用功能，如网关和路由中继。

这个想法源于缺乏这样的包，并且为了避免在控制器、模型等中使用数百万行的注释来污染它们。注释也缺乏使用变量作为值的特性。

此包使用 cebe/php-openapi 来处理大部分繁重的工作，包括规范验证。感谢这个优秀的包！

特性

从模型类自动生成基本的模式定义。
自动生成大多数 REST API 所使用的常见 HTTP 响应。
整个规范都存储在一个配置文件中，整齐有序。
使用简单的数组创建任何 OpenApi 对象。

安装

在您的 composer.json 中添加 jeandormehl/openapi-gen 包并在更新依赖关系

$ composer require jeandormehl/openapi-gen

Laravel

将 Rapid\OAS\Providers\ServiceProvider 添加到您的 config/app.php 提供者数组中。

发布最小配置

$ php artisan vendor:publish --provider="Rapid\OAS\Providers\ServiceProvider"

注意：由于 Dingo 使用与 Laravel/Lumen 不同的服务提供者，因此未使用包自动发现。将来会找到一种方法将它们全部组合到一个提供者中。

Lumen

复制配置文件

$ mkdir -p config
$ cp -R vendor/jeandormehl/openapi-gen/config/oas.php config/oas.php

将配置加载到 bootstrap/app.php

$app->configure('oas');

注册服务提供者

$app->register(Rapid\OAS\Providers\ServiceProvider::class);

Dingo

根据您使用的内容，遵循 Laravel 或 Lumen 的说明。

在注册服务提供者时，将其替换为 Rapid\OAS\Providers\DingoServiceProvider::class

注意：当使用 Dingo 时，您的 API_PREFIX 将被添加到已注册的路由之前。

配置

oas.php 文件包含您的整个规范，根据其内容，将生成规范。还提供了基本验证，所以如果您的配置文件中有错误，包应该会给出有关如何纠正问题的提示。

该文件由与 OpenApi 规范匹配的数组组成。当我创建这个包时，OpenApi 正在使用的版本是 3.0.2。

以下是一些确保您配置文件有效性的有用链接

route

route 键控制用于访问规范的注册路由。在这里您可以选择启用/禁用路由，设置路径和前缀，如果需要的话添加中间件。

  ...

  'route' => [
      'enabled'    => true,
      'prefix'     => '',
      'path'       => 'docs',
      'middleware' => [],
  ],

  ...

注意：当使用 Dingo 时，您的 API_PREFIX 将被添加到已注册的路由之前。

yaml

yaml 键定义了输出规范为 .yml 文件的路径。默认情况下，文件放置在 storage/app/oas.yml。要生成 yaml 文件，请运行以下 artisan 命令

$ php artisan oas:yaml

openapi

openapi 键指定 OAS 版本。默认为 3.0.2。

  ...

  'openapi' => \Rapid\OAS\OpenApi::VERSION,

  ...

请参阅 oasObject 了解更多信息。

info

info 键代表 OAS info 对象。

最小配置

  ...

  'info' => [
      'title'   => 'OpenApi',
      'version' => env('API_VERSION') ?? env('APP_VERSION', 'v1'),
  ],

  ...

完整配置

  ...

  'info' => [
      'title'          => 'OpenApi',
      'description'    => 'This is the OpenApi specification package.',
      'termsOfService' => 'https:///termsOfService',
      'contact'        => [
          'name'  => 'John Smith',
          'url'   => 'https:///me',
          'email' => 'john.smith@company.com',
      ],
      'license' => [
          'name' => 'Apache-2.0',
          'url'  => 'https://apache.ac.cn/licenses/LICENSE-2.0',
      ],
      'version' => env('API_VERSION') ?? env('APP_VERSION', 'v1'),
  ],

  ...

请参阅infoObject获取更多信息。

服务器

servers键包含OAS服务器对象的数组。

最小配置

  ...

  'servers' => [
      [
          'url' => 'https://:8080/v1',
      ],
  ],

  ...

完整配置

  ...

  'servers' => [
      [
          'url'         => 'https://:8080/v1',
          'description' => 'OpenApi HTTP Server',
          // server variables
          'variables'   => [
              'scheme' => [
                  'enum'        => ['http', 'https'],
                  'default'     => 'http',
                  'description' => 'The Transfer Protocol',
              ],
          ],
      ],
  ],

  ...

请参阅serverObject和serverVariableObject获取更多信息。

安全

security键定义了安全需求对象。每个属性使用的名称必须与在components对象下声明的securityScheme对应。这些是全球范围内使用API所必需的。如果安全方案类型为oauth2或openIdConnect，则值是执行所需的范围名称列表。对于其他安全方案类型，数组必须为空。

最小配置

  ...

  'security' => [
      'apiKey' => [],
      // if using oauth
      'oauth2' => [
          'view:users',
          'create:users',
      ],
  ],

  ...

完整配置

  ...

  'security' => [
      'apiKey' => [],
      'http'   => [],
      'bearer' => [],
      'oauth2' => [
          'view:users',
          'create:users',
      ],
      'openIdConnect' => [
          'view:users',
          'create:users',
      ],
  ],

  ...

请参阅securityRequirementObject获取更多信息。

  ...
  'tags' => [
      [
          'name'         => 'User',
          'description'  => 'API user models.',
          // see externalDocs section
          'externalDocs' => [
              'url'         => 'https:///tags/users/externalDocs',
              'description' => 'User docs.',
          ],
      ],
  ],
  ...

请参阅tagObject获取更多信息。

外部文档

externalDocs键包含外部文档OAS对象。

最小配置

  ...

  'externalDocs' => [
      'url' => 'https:///externalDocs',
  ],

  ...

完整配置

  ...

  'externalDocs' => [
      'url'         => 'https:///externalDocs',
      'description' => 'External docs for OpenApi.',
  ],

  ...

请参阅externalDocumentationObject获取更多信息。

组件

components键。请参阅componentsObject。

Schemas

schemas键。请参阅schemaObject。

自动生成模型模式

此包允许您根据Eloquent模型自动生成基本模式。在模型数组内提供一个Fully Qualified Class Names (FQCN)数组，该包将尝试为您创建模式，这些模式可以在其他键中稍后引用。

注意：目前支持MySQL、SQLite、PostgreSQL和Oracle。

注意：这些模式定义非常基础，仅包含以下值

标题
描述
必需
属性

属性将仅包含以下属性

描述
类型
格式
可为空
默认值

在模型隐藏数组内部和配置hidden标签内部定义的属性将不会包含在模式中。

最小配置

  ...

  'components' => [
      'schemas' => [
            ...

            'models' => ['App\\User' => []],

            ...
      ],
  ],

  ...

完整配置

  ...

  'components' => [
      'schemas' => [
            ...

            'models' => [
                'App\\User' => [
                    'hidden' => ['password', 'updated_at', 'deleted_at']
                ],
            ],

            ...
      ],
  ],

  ...

标准模式对象

schemas键代表OAS模式对象的数组。在这里，您可以定义自定义模式，并在稍后配置中引用它们。强烈建议在这里定义所有模式，然后在配置中简单地引用它们，而不是创建内联模式，尽管此功能确实存在。

示例枚举模式

  ...

  'components' => [
      'schemas' => [
          ...

          'Status' => [
              'title'       => 'Status',
              'description' => 'Current status of the user.',
              'enum'        => ['Active', 'Pending', 'Disabled'],
              'default'     => 'Pending',
              'type'        => \cebe\openapi\spec\Type::STRING,
          ],

          ...
      ],
  ],

  ...

示例对象模式

  ...

  'components' => [
      'schemas' => [
          ...

          'User' => [
              'title'       => 'User',
              'description' => 'The User object.',
              'type'        => \cebe\openapi\spec\Type::OBJECT,
              'required'   => ['email', 'status'],
              'properties' => [
                  'email' => [
                      'type' => \cebe\openapi\spec\Type::STRING,
                      'title' => 'Email',
                      'description' => 'The users email address.',
                      // pattern => '',
                  ],
                  'first_name' => [
                      'type' => \cebe\openapi\spec\Type::STRING,
                      'title' => 'FirstName',
                      'description' => 'The users first name.',
                  ],
                  // $refs should always be an array as seen here
                  'status' => ['$ref' => '#/components/schemas/Status']
              ],
              'maxProperties' => 3,
              'minProperties' => 3,
          ],

          ...
      ],
  ],

  ...

注意：schema OAS对象包含许多属性，具体取决于您使用的模式定义类型。

请参阅schemaObject以获取所有其他属性和类型。

Responses

自动生成常见HTTP响应

responses键包含一个名为statusCodes的键，它定义了在几乎所有REST API中使用的常见HTTP响应。此键仅是一个包含HTTP状态代码的数组，它将生成响应。目前，生成的所有响应都是application/json，可以在您的规范中的任何地方引用。

注意：除非你只想返回给API消费服务200 OK响应，否则请不要在这里定义200 OK响应。200响应通常应在使用schema和requestBodies $refs的paths或operations中定义。

配置

  ...

  'components' => [
      ...

      'responses' => [
          ...

          // common responses use application/json content types.
          'statusCodes' => [400, 401, 403, 404, 405, 418, 422, 500, 502, 503],

          ...
      ],
  ],

  ...

标准响应对象

responses键代表一组OAS响应对象。在这里，你可以定义自定义响应，并在配置中稍后引用它们。强烈建议在这里定义所有响应，并在配置中简单地引用它们，而不是创建内联响应，尽管功能是存在的。

配置

  ...

  'components' => [
      ...

      'responses' => [
          ...

          'TokenResponse' => [
              'description' => 'The oauth2 token response.',
              'content'     => [
                  // mediaType object
                  'application/json' => [
                      // using schemas $ref. Try to stick to $refs but inline can also be used
                      'schema' => ['$ref' => '#/components/schemas/TokenResponse'],
                  ],
              ],
          ],

          ...
      ],
  ],

  ...

Parameters

parameters键用于指定参数，可以在规范中的任何地方引用。强烈建议在此键中定义所有parameters，并在整个规范中引用它们。

配置

  ...

  'components' => [
      ...

      'parameters' => [
          ...

          'Identifier' => [
              'name'            => 'Identifier',
              'in'              => 'path',
              'description'     => 'The model identifier',
              'required'        => true,
              'deprecated'      => false,
              'allowEmptyValue' => false,

              // you can use inline schema objects here but its highly recommended to use $refs to schema objects
              'schema' => ['$ref' => '#components/schemas/Identifier'],
              // 'schema' => [
              //     'type'    => \cebe\openapi\spec\Type::INTEGER,
              //     'format'  => \Rapid\OAS\Spec\Format::INT32,
              //     'example' => 1,
              // ],
          ],

          ...
      ],
  ],

  ...

有关更多信息，请参阅parameterObject。

RequestBodies

requestBodies键代表一组OAS requestBody对象。建议在规范中定义所有requestBodies，并在需要的地方简单地引用它们。

配置

  ...

  'components' => [
      ...

      'requestBodies' => [
          ...

          'User' => [
              'description' => 'User request body.',
              'required'    => true,
              'content'     => [
                  'application/json' => [
                      // using schema $ref. Inline can also be specified.
                      'schema'  => ['$ref' => '#/components/schemas/User'],
                  ],
              ],
          ],

          ...
      ],

      ...
  ],

Headers

headers键代表一组OAS header对象。建议在规范中定义所有headers，并在需要的地方简单地引用它们。

最小配置

  ...

  'components' => [
      ...

      'headers' => [
          ...

          'X-User-Id' => [
              'description' => 'The User Identifier passed between microservices.',
              'required'   => true,
              'deprecated' => false,
              // use $ref wherever possible
              'schema' => ['$ref' => '#/components/schemas/Identifier'],
          ],

          ...
      ],

      ...
  ],

完整配置

  ...

  'components' => [
      ...

      'headers' => [
          ...

          'Accept' => [
              'description' => 'The Accept header to pass to all requests.',
              'required'    => true,
              'deprecated'  => false,
              'content'     => [
                  // mediaType object
                  'application/json' => [
                      // using an inline schemas. Try to stick to $refs
                      'schema' => ['type' => \cebe\openapi\spec\Type::STRING],
                      'examples' => [
                          'application/json' => ['value' => 'application/json'],
                          'application/vnd.github.v3+json' => ['value' => 'application/vnd.github.v3+json'],
                      ],
                  ],
              ],
          ],

          ...
      ],

      ...
  ],

有关如何创建这些对象的更多信息，请参阅headerObject和mediaTypeObject。

SecuritySchemes

securityScheme键。这些直接链接到security键，应在使用security或operation对象之前定义。

完整配置

  ...

  'components' => [
      ...

      'securitySchemes' => [
          ...

          // apiKey example
          'apiKey' => [
              'type'        => 'apiKey',
              'description' => 'Unique key used to authenticate against API.',
              'name'        => 'X-Application-Id',
              'in'          => 'header',
          ],

          // possible http schemes: basic, bearer
          // basic example
          'basic' => [
              'type'        => 'http',
              'description' => 'HTTP basic scheme to authenticate against API.',
              'scheme'      => 'basic',
          ],

          // bearer example
          'bearer' => [
              'type'         => 'http',
              'description'  => 'HTTP bearer scheme to authenticate against API.',
              'scheme'       => 'bearer',
              'bearerFormat' => 'bearer',
          ],

          // oauth2 example
          'oauth2' => [
              'type'        => 'oauth2',
              'description' => 'OAuth2 authentication flows to authenticate against API.',
              'flows' => [
                  // implicit
                  'implicit' => [
                      'authorizationUrl' => 'https:///authorizationUrl',
                      'scopes'           => [
                          'view:users'   => 'View all user information',
                          'create:users' => 'Create a new user.',
                      ],
                  ],

                  // password
                  'password' => [
                      'tokenUrl'   => 'https:///tokenUrl',
                      'refreshUrl' => 'https:///refreshUrl',
                      'scopes'     => [
                          'view:users'   => 'View all user information',
                          'create:users' => 'Create a new user.',
                      ],
                  ],

                  // clientCredentials
                  'clientCredentials' => [
                      'tokenUrl'   => 'https:///tokenUrl',
                      'refreshUrl' => 'https:///refreshUrl',
                      'scopes'     => [
                          'view:users'   => 'View all user information',
                          'create:users' => 'Create a new user.',
                      ],
                  ],

                  // authorizationCode
                  'authorizationCode' => [
                      'authorizationUrl' => 'https:///authorizationUrl',
                      'tokenUrl'         => 'https:///tokenUrl',
                      'scopes'           => [
                          'view:users'   => 'View all user information',
                          'create:users' => 'Create a new user.',
                      ],
                  ],
              ],
          ],

          // openIdConnect example
          'openIdConnect' => [
              'type'             => 'openIdConnect',
              'description'      => 'OpenIdConnect authentication for API.',
              'openIdConnectUrl' => 'https://open.id/connect',
          ],

          ...
      ],

      ...
  ],

有关更多详细信息，请参阅securitySchemeObject、oauthFlowsObject和oauthFlowObject。

paths

paths键。请参阅pathsObject。

这是整个配置中最重要的键。这将定义你的路径和操作。尽可能仅使用$refs，并尽可能使此配置干净整洁。

  ...

  'paths' => [
      // path item
      '/users' => [
          // operation (GET)
          'get' => [
              'tags'        => ['User'],
              'summary'     => 'Get Users',
              'description' => 'Get a paginated result set of User objects.',
              'operationId' => 'user.index',
              // try stick to $refs
              'responses'   => [
                  '200' => ['$ref' => '#/components/responses/UsersList'],
                  '400' => ['$ref' => '#/components/responses/400'],
                  '401' => ['$ref' => '#/components/responses/401'],
                  '403' => ['$ref' => '#/components/responses/403'],
              ],
          ],

          // operation (POST)
          'post' => [
              'tags'        => ['User'],
              'summary'     => 'Create User',
              'description' => 'Create a new user.',
              'operationId' => 'user.create',
              'requestBody' => ['$ref' => '#/components/requestBodies/User'],
              'responses' => [
                  '200' => ['$ref' => '#/components/responses/User'],
                  '400' => ['$ref' => '#/components/responses/400'],
                  '401' => ['$ref' => '#/components/responses/401'],
                  '403' => ['$ref' => '#/components/responses/403'],
                  '404' => ['$ref' => '#/components/responses/404'],
                  '418' => ['$ref' => '#/components/responses/418'],
                  '422' => ['$ref' => '#/components/responses/422'],
              ],
          ],
      ],
  ],

  ...

待办事项

将examples对象添加到规范中。请参阅exampleObject。
将links对象添加到规范中。请参阅linkObject。
将callbacks对象添加到规范中。请参阅callbackObject。

许可证

在Apache-2.0许可下发布，请参阅LICENSE。

jeandormehl / openapi-gen

维护者

详细信息

README

关于

目录

特性

安装

Laravel

Lumen

Dingo

配置

route

yaml

openapi

info

服务器

安全

标签

外部文档

组件

Schemas

自动生成模型模式

标准模式对象

Responses

自动生成常见HTTP响应

标准响应对象

Parameters

RequestBodies

Headers

SecuritySchemes

paths

待办事项

许可证