Download the PHP package greensystemes/oa-doc-parser without Composer

OpenApi Doc Parser

OpenApi Doc Parser can extract OpenApi from your PHP code. This program is in case of PHP code isn't generate from OpenApi specification. Why is it usefull :

• You don't have to update an OpenApi file from a change in PHP code (vice-versa);
• Simple usage;
• Json PHP base extension is needed, no external dependencies at runtime. Just PHPUnit for tests;
• Scan your PSR4 namespaces thanks to your composer.json;
• OpenApi documentations must be write in yaml file format.

Need PHP 7.4 to run ! Why ? Just to make the code bugless and more readable.

Actually, the tool respond to our usage. But, you can make a PR if you see missing feature.

Features :

• Can take a Swagger base file;
• Create components;
• Properties documentation of components can be add in class properties documentations;
• Work with enum components;
• Detect duplicates components;
• Create routes;
• Detect duplicate routes;
• Make partial Swagger with properties flagged (partial swagger for some customers for example);
• Configuration file.

TODO

• [ ] Make tests !
• [ ] Check OpenApi $ref are valid.

Usage

Command line

./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

Required parameters :

• --composer : Your composer file. Used to extract your PSR4 namespaces;
• --swagger-header : Your Swagger PSR4 header file. See below for more information;
• --swagger-output : File that will be write by this tool. If file exists, it will be overwrite.

Optional parameter :

• --tag : Can be used more that one time. Define tag use filter component and route for partial swagger. If no --tag set, no filtering will be made;
• --autoload : Path to autoload.php in vendor directory.

Configuration file

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

Your OA-Doc-Parser.json should be define as :

{
    "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"
        ]
    }
}

Required parameters :

• composer : Your composer file. Used to extract your PSR4 namespaces;
• swagger.header : Your Swagger PSR4 header file. See below for more information;
• swagger.output: File that will be write by this tool. If file exists, it will be overwrite.

Optional parameter :

• swagger.partial : String array, define tag use filter component and route for partial swagger. If no swagger.partial set, no filtering will be made;
• autoload : Path to autoload.php in vendor directory.

Swagger header

Your swagger-header.yml must be write in YAML and need to contains :

• Open Api version
• info object
• servers object

Open Api Documentation here

Like that for example :

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

Commenting your code

Component annotations

@OA-Name

Name of component, aka. PHP object name. Should use a constructor comment.

/**
 * @OA-Name MyObjectName
 */

@OA-Component-Begin and @OA-Component-End

yaml of Component object

Use to describe object. Should use a constructor comment.

DO NOT PUT PROPERTIES KEY !

/**
 * @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 and @OA-Property-End

Use to describe each property of object. Should use a property comment.

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

Path annotations

All of path annotations should be add in method comment.

@OA-Method

Method used on that method. Values can be one of them : GET, POST, DELETE, PUT, OPTIONS, HEAD, PATCH or TRACE

/**
 * @OA-Method POST
 */

@OA-Path

Path for that method

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

@OA-Path-Begin and @OA-Path-End

yaml of Operation object

/**
 * @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

List of tags used if partial tags are defined in configuration.

You can name you tags by respecting that regex [A-Za-z0-9_-]. Space separate tags

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

Examples

Controller

<?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
    }
}

Objects

Common

<?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;
}

Enum

<?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
}

Tests

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