wapmorgan / openapi-generator
OpenApi configuration generator directly from PHP code (PhpDoc and php type hints). Can be used with a large monolithic backend
Installs: 2 698
Dependents: 0
Suggesters: 0
Security: 0
Stars: 3
Watchers: 1
Forks: 2
Open Issues: 0
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
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.
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
- Scraper collects info about specifications, tags, security schemes and servers, and lists all endpoints.
- 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
. whereSCRAPER
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 withobject
,array
,stdclass
,mixed
type or class-typed, method of argument will be changed toPOST
and these arguments will be placed asbody
data in json-format.DefaultGenerator::TREAT_COMPLEX_ARGUMENTS_AS_BODY
-DefaultGenerator::PARSE_PARAMETERS_FROM_ENDPOINT
- if callbackid
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, forstring
format there are subtypes:date
,date-time
,password
,byte
,binary
, forinteger
there are:float
,double
,int32
,int64
. Also, you can defined custom format withDefaultGenerator::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=...¶m2=...
) 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)