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