wapmorgan/openapi-generator

OpenApi configuration generator directly from PHP code (PhpDoc and php type hints). Can be used with a large monolithic backend

0.3.1 2022-02-22 20:07 UTC

Requires

• php: >=7.1.0
• doctrine/annotations: ^1.6
• phpdocumentor/reflection-docblock: ^4.3|^5.1
• symfony/console: ^5.0
• zircote/swagger-php: ^3.0

MIT

• wapmorgan

• documentation
• api
• swagger
• openapi
• openapi-generator
• swagger-generator

README

It is OpenApi configuration generator that works with origin source code.

Main purpose of this library is to simplify OpenApi-specification generation for existing API with a lot of methods and especially automatize it to avoid manual changes. Idea by @maxonrock.

1. What it does
2. How it works
3. How to use
4. Integrations
5. New scraper
6. Settings
7. Limitations
8. ToDo

What it does

It generates OpenApi 3.0 specificaton files for your REST API written in PHP from source code based on any framework or written manually, whatever.

How it works

1. Scraper collects info about specifications, tags, security schemes and servers, and lists all endpoints.
2. Generator fulfills openapi-specification with endpoints information:
   • summary and description (first line and rest of php-doc)
   • parameters: from php-doc: @param/@paramEnum/@paramExample/@paramFormat, from function signature: string $text.
   • result declared in php-doc (@return SendMessageResponse)

More detailed process description is in How it works document.

How to use

• Parse and compose list of endpoints - ./vendor/bin/openapi-generator scrape --scraper SCRAPER.
• Generate specifications - ./vendor/bin/openapi-generator generate --scraper SCRAPER --generator GENERATOR. where SCRAPER is a class or file with scraper.

More detailed description is in How to use document.

Integrations

There's few integrations: yii2, laravel, slim. More detailed description is in Integrations document.

New scraper

You use (or extend) a predefined scraper (see Integrations) or create your own scraper from scratch (extend DefaultScraper), which should return a result with list of your API endpoints. Also, your scraper should provide tags, security schemes and so on.

Scraper should returns list of specifications (for example, list of api versions) with data in each specification:

• version - unique ID of specification.
• description - summary of specification.
• externalDocs - URL to external docs.
• servers - list of servers (base urls).
• tags - list of tags with description and other properties.
• securitySchemes - list of security schemes (authorization types).
• endpoints - list of API endpoints.

Detailed information about Scraper result: in another document.

Settings

DefaultGenerator provides list of settings to tune generator.

• DefaultGenerator::CHANGE_GET_TO_POST_FOR_COMPLEX_PARAMETERS - if callback has arguments with object, array, stdclass, mixed type or class-typed, method of argument will be changed to POST and these arguments will be placed as body data in json-format.
• DefaultGenerator::TREAT_COMPLEX_ARGUMENTS_AS_BODY -
• DefaultGenerator::PARSE_PARAMETERS_FROM_ENDPOINT - if callback id has macroses (users/{id}), these arguments will be parsed as normal callback arguments.
• DefaultGenerator::PARSE_PARAMETERS_FORMAT_FORMAT_DESCRIPTION - if php-doc for callback argument in first word after argument variable has one of predefined sub-types (@param string $arg SUBTYPE Full parameter description ), this will change sub-type in resulting specification. For example, for string format there are subtypes: date, date-time, password, byte, binary, for integer there are: float, double, int32, int64. Also, you can defined custom format with DefaultGenerator::setCustomFormat($format, $formatConfig).

Usage:

$generator->changeSetting(DefaultGenerator::CHANGE_GET_TO_POST_FOR_COMPLEX_PARAMETERS, true);

By default, they all are disabled.

Limitations

• Only query parameters supported (url?param1=...&param2=...) or body json parameters ({data: 123).
• Only one response type supported - HTTP 200 response.
• No support for parameters' / fields' / properties' format, example and other validators.

ToDo

• Support for few operations on one endpoint (GET/POST/PUT/DELETE/...).
• Support for body parameters (when parameters are complex objects) - partially.
• Support for few responses (with different HTTP codes).
• Extracting class types into separate components (into openapi components).
• Add @paramFormat for specifying parameter format - partially.
• Support for dynamic action arguments in dynamic model
• Switch 3.0/3.1 (https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0)