PHPackages                             greensystemes/oa-doc-parser - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. greensystemes/oa-doc-parser

ActiveLibrary

greensystemes/oa-doc-parser
===========================

OpenApi Doc Parser : Merge YAML OpenApi and PHP

0.0.4(5y ago)09GPL-2.0-onlyPHPPHP >=7.4CI failing

Since May 6Pushed 5y ago3 watchersCompare

[ Source](https://github.com/GreenSystemes/OA-Doc-Parser)[ Packagist](https://packagist.org/packages/greensystemes/oa-doc-parser)[ RSS](/packages/greensystemes-oa-doc-parser/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (4)Dependencies (8)Versions (6)Used By (0)

OpenApi Doc Parser
==================

[](#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
----

[](#todo)

- Make tests !
- Check OpenApi `$ref` are valid.

Usage
-----

[](#usage)

### Command line

[](#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

[](#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

[](#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](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md)

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

[](#commenting-your-code)

### Component annotations

[](#component-annotations)

#### @OA-Name

[](#oa-name)

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

```
/**
 * @OA-Name MyObjectName
 */

```

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

[](#oa-component-begin-and-oa-component-end)

`yaml` of [Component object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#componentsObject)

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

[](#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

[](#path-annotations)

All of path annotations should be add in method comment.

#### @OA-Method

[](#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

[](#oa-path)

Path for that method

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

```

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

[](#oa-path-begin-and-oa-path-end)

`yaml` of [Operation object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#operationObject)

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

[](#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

[](#examples)

#### Controller

[](#controller)

```