README

OpenApi Doc Parser 可以从您的 PHP 代码中提取 OpenApi。如果您的 PHP 代码不是由 OpenApi 规范生成，则此程序将很有用。

您无需从 PHP 代码（反之亦然）的更改中更新 OpenApi 文件；
简单使用；
需要 Json PHP 基础扩展，运行时无外部依赖。仅 PHPUnit 用于测试；
通过您的 composer.json 扫描您的 PSR4 命名空间；
OpenApi 文档必须以 yaml 文件格式编写。

需要 PHP 7.4 来运行！为什么？只是为了使代码无错误且更易读。.

实际上，该工具响应我们的使用。但是，如果您看到缺少的功能，可以提交一个 PR。

功能

可以接受 Swagger 基础文件；
创建组件；
可以添加组件属性文档到类属性文档中；
与枚举组件一起工作；
检测重复组件；
创建路由；
检测重复路由；
创建带有标记属性的 Swagger 部分文档（例如为某些客户提供部分 Swagger）；
配置文件。

待办事项

编写测试！
检查 OpenApi $ref 是否有效。

使用方法

命令行

./oa-doc-parser
        --composer ./path/to/your/composer.json
        --swagger-header ./path/to/your/swagger-header.yml
        --swagger-output ./path/to/your/output-swagger.yml

必需参数

--composer : 您的 composer 文件。用于提取您的 PSR4 命名空间；
--swagger-header : 您的 Swagger PSR4 标头文件。见下文了解更多信息；
--swagger-output : 由该工具写入的文件。如果文件存在，它将被覆盖。

可选参数

--tag : 可以多次使用。定义标签以过滤部分 Swagger 中的组件和路由。如果没有设置 --tag，则不进行过滤；
--autoload : vendor 目录中 autoload.php 的路径。

配置文件

./oa-doc-parser
        --conf ./path/to/your/OA-Doc-Parser.json

您的 OA-Doc-Parser.json 应定义如下

{
    "composer": "./path/to/your/composer.json",
    "autoload": "./path/to/your/autoload.php",
    "swagger": {
        "header": "./path/to/your/swagger-header.yml",
        "output": "./path/to/your/output-swagger.yml",
        "partial": [
            "TAG1", "TAG2"
        ]
    }
}

必需参数

composer : 您的 composer 文件。用于提取您的 PSR4 命名空间；
swagger.header : 您的 Swagger PSR4 标头文件。见下文了解更多信息；
swagger.output: 由该工具写入的文件。如果文件存在，它将被覆盖。

可选参数

swagger.partial : 字符串数组，定义标签以过滤部分 Swagger 中的组件和路由。如果没有设置 swagger.partial，则不进行过滤；
autoload : vendor 目录中 autoload.php 的路径。

Swagger 标头

您的 swagger-header.yml 必须以 YAML 编写，并需要包含以下内容：

OpenApi 版本
info 对象
servers 对象

OpenApi 文档在这里

例如：

openapi: 3.0.0
info:
  title: Your title
  description: Api to interact with the Green Solution
  version: 0.1.29
servers:
  - url: 'https://server.acme'
tags:
  - name: Users
    description: Manage Users
  - name: User Things
    description: Manage User thing

注释您的代码

组件注解

@OA-Name

组件名称，即 PHP 对象名称。应使用构造器注释。

/**
 * @OA-Name MyObjectName
 */

@OA-Component-Begin 和 @OA-Component-End

组件对象的 yaml

用于描述对象。应使用构造器注释。

不要放属性键！

/**
 * @OA-Component-Begin
 * type: object
 * description: Object usefull to ....
 * example:
 *   id: 42
 *   name: 'Dev team'
 *   quota: 3.14
 *   period: 2
 * @OA-Component-End
 */

@OA-Property-Begin 和 @OA-Property-End

用于描述对象的每个属性。应使用属性注释。

/**
 * @OA-Property-Begin
 * propertyNameYouWant:
 *   type: integer
 *   description: That property do ...
 * @OA-Property-End
 */

路径注解

所有路径注解都应添加到方法注释中。

@OA-Method

该方法使用的方法。值可以是以下之一：GET、POST、DELETE、PUT、OPTIONS、HEAD、PATCH或TRACE

/**
 * @OA-Method POST
 */

@OA-Path

该方法的路径

/**
 * @OA-Path /acme/users/{id}/foo
 */

@OA-Path-Begin和@OA-Path-End

yaml的操作对象

/**
 * @OA-Path-Begin
 * tags:
 * - Users
 * summary: Updates a user in the store with form data
 * operationId: updateUserWithForm
 * parameters:
 * - name: userId
 *   in: path
 *   description: ID of user that needs to be updated
 *   required: true
 *   schema:
 *     type: string
 * requestBody:
 *   content:
 *     'application/x-www-form-urlencoded':
 *     schema:
 *     properties:
 *       name: 
 *         description: Updated name of the user
 *         type: string
 *       status:
 *         description: Updated status of the user
 *         type: string
 *     required:
 *       - status
 * responses:
 *   '200':
 *     description: User updated.
 *     content: 
 *       'application/json': {}
 *       'application/xml': {}
 * @OA-Path-End
 */

@OA-Partial-Tags

如果在配置中定义了部分标签，则使用这些标签的列表。

您可以通过遵守以下正则表达式来命名您的标签：[A-Za-z0-9_-]。用空格分隔标签

/**
 * @OA-Partial-Tags CustomerApi AcmeCompanyApi BackOfficeApi
 */

示例

控制器

<?php

class UserController {
    /**
     * @OA-Method GET
     * @OA-Path /acme/users/{id}
     * @OA-Partial-Tags CustomerApi AcmeCompanyApi
     * @OA-Path-Begin
     * tags:
     * - Users
     * summary: Get a user in the store
     * operationId: getUser
     * parameters:
     * - name: userId
     *   in: path
     *   description: ID of user that needs to be updated
     *   required: true
     *   schema:
     *     type: integer
     * responses:
     *   '200':
     *     description: User data
     *     content: 
     *       'application/json': {}
     *       'application/xml': {}
     * @OA-Path-End
     */
    public function getUserAction( Request $request, Responses $response, array $args ) : Response {
        //Some things
    }
}

对象

通用

<?php

/**
 * @OA-Name MyObject
 * @OA-Component-Begin
 * type: object
 * description: Object usefull to ....
 * example:
 *   id: 42
 *   name: 'Dev team'
 *   quota: 3.14
 *   period: 2
 * @OA-Component-End
 */
class MyObject {
    /**
     * @OA-Property-Begin
     * id:
     *   type: integer
     *   description: Global ID
     * @OA-Property-End
     */
    private int $id;

    /**
     * @OA-Property-Begin
     * name:
     *   type: string
     *   description: Name of user
     * @OA-Property-End
     */
    private string $name;

    /**
     * @OA-Property-Begin
     * quota:
     *   type: float
     *   description: Quota of actions
     * @OA-Property-End
     */
    private float $quota;
}

枚举

<?php

/**
 * @OA-Name MyEnumObject
 * @OA-Component-Begin
 * type: integer
 * nullable: true
 * enum:
 *   - 0
 *   - 1
 *   - 2
 * description: >
 *   Your super description
 *    * `0` **UNDEFINED** : No quota rule;
 *    * `1` **HALF** : Quota limited to week (Monday to Sunday);
 *    * `2` **FULL** : Quota limited to month (1st to 28th/29th/30th/31th);
 * @OA-Component-End
 */
class MyEnum {
    //Some things
}

测试

docker run -ti --rm -v `pwd`:/home/builder tracesoftware/gitlab-builder:php7-cli composer install && composer all

greensystemes / oa-doc-parser

维护者

详细信息