{"id":14986634,"url":"https://github.com/vanderlee/phpswaggergen","last_synced_at":"2025-04-13T04:09:24.889Z","repository":{"id":18703082,"uuid":"21913434","full_name":"vanderlee/PHPSwaggerGen","owner":"vanderlee","description":"PHP library to generate Swagger/OpenAPI REST API documentation files from comments in PHP source code.","archived":false,"fork":false,"pushed_at":"2024-04-11T12:08:24.000Z","size":1845,"stargazers_count":41,"open_issues_count":3,"forks_count":16,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-13T04:09:21.369Z","etag":null,"topics":["documentation","documentation-generator","hhvm","openapi","openapi-spec","php","php5","php53-compatible","php7","rest","rest-api","restful","restful-api","restful-api-php","swagger","swagger-spec","swagger2"],"latest_commit_sha":null,"homepage":"http://vanderlee.github.io/PHPSwaggerGen","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vanderlee.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-07-16T19:06:38.000Z","updated_at":"2024-07-03T15:40:25.000Z","dependencies_parsed_at":"2024-06-19T16:02:01.316Z","dependency_job_id":"debb06cc-a8c0-4b37-8925-561649d26d8b","html_url":"https://github.com/vanderlee/PHPSwaggerGen","commit_stats":{"total_commits":346,"total_committers":14,"mean_commits":"24.714285714285715","dds":0.2341040462427746,"last_synced_commit":"9d82ae60586ab20c44f280acedda57c5f8309dad"},"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanderlee%2FPHPSwaggerGen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanderlee%2FPHPSwaggerGen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanderlee%2FPHPSwaggerGen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanderlee%2FPHPSwaggerGen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vanderlee","download_url":"https://codeload.github.com/vanderlee/PHPSwaggerGen/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248661704,"owners_count":21141450,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","documentation-generator","hhvm","openapi","openapi-spec","php","php5","php53-compatible","php7","rest","rest-api","restful","restful-api","restful-api-php","swagger","swagger-spec","swagger2"],"created_at":"2024-09-24T14:13:15.670Z","updated_at":"2025-04-13T04:09:24.847Z","avatar_url":"https://github.com/vanderlee.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SwaggerGen\nVersion 2.3.22\n\n[![License](https://img.shields.io/github/license/vanderlee/PHPSwaggerGen.svg)]()\n[![Build Status](https://travis-ci.org/vanderlee/PHPSwaggerGen.svg?branch=master)](https://travis-ci.org/vanderlee/PHPSwaggerGen)\n[![Quality](https://scrutinizer-ci.com/g/vanderlee/PHPSwaggerGen/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/vanderlee/PHPSwaggerGen)\n\nCopyright \u0026copy; 2014-2024 Martijn van der Lee [Toyls.com](http://toyls.com).\n\nMIT Open Source license applies.\n\n## Introduction\nSwaggerGen is a PHP library for generating [Swagger](http://swagger.io/) REST\nAPI documentation from PHP source code.\n\nIt reads comments starting with `@rest\\`, containing commands describing the\nAPI as you go.\nWorking with SwaggerGen is intended to be a natural extension to normal\nPHP-documentor style documentation.\nYou can describe a REST API call similar to how you would describe method.\n\nUsing just a few simple commands like `@rest\\endpoint /users` and\n`@rest\\method GET Get a list of all users` gets you a definition of an API.\nBy adding a `@rest\\response 200 array(object(name:string, age:int[0,\u003e, gender:enum(male,female)))`\nstatement, you've just defined exactly what it'll return.\nYou could have also just defined a `User` and do the same with a\n`@rest\\response 200 array(User)` statement or even just `@rest\\response ok [User]`.\n\nSwaggerGen makes it quick and intuitive to write high quality documentation.\n\nUse [Swagger-UI](https://github.com/swagger-api/swagger-ui) to read and test\nyour API, as in this example generated real-time with SwaggerGen:\n[Example](example/docs/) (only available when running on a PHP server).\n\nSwaggerGen is compatible with the latest\n[Swagger 2.0 specification](http://swagger.io/specification/),\nwhich forms the basis of the [Open API Initiative](https://openapis.org/).\n\n## Installation\nRequires PHP 5.4 or greater. PHP 5.3 is supported as long as no more recent\nfeatures are absolutely necessary. There is no guarantee SwaggerGen will\ncontinue to work on PHP 5.3 in the future.\n\nTo install using Composer:\n\n\tcomposer require vanderlee/swaggergen\n\nMake sure you use version 2.x.x or up.\n\nSwaggerGen aims to be PSR-4 compatible, so you should be able to use it in any\npackage manager.\n\n## Using SwaggerGen\nThe easiest part of generating Swagger documentation with SwaggerGen is setting\nit up.\n\n1.\tSet up your (PSR-0, PSR-4 or custom) autoloader to use the SwaggerGen\n\tdirectory.\n\n\tYou can take a look at the autoloader in the example folder if you don't\n\talready have an autoloader.\n\n2.\tCreate an instance of the `/SwaggerGen/SwaggerGen` class.\n\n\tYou can (and are advised to) specify the domainname of your server and the\n\tpath to the API in the constructor.\n\n3.\tCall the `array SwaggerGen-\u003egetSwagger(string[] $filenames)` method to\n\tgenerate the documentation.\n\n\tJust provide the files which contain the operation definitions of your API.\n\tIf your API uses other files, just specify an array of directories in the\n\t`SwaggerGen` constructor and these files will be automatically parsed when\n\tneeded.\n\n4.\tYou're done. Your documentation is generated. All that's left to do is\n\toutput it. Store it in a file or return it real-time.\n\nIf you want to use the preprocessor, you'll probably want to call the\n`SwaggerGen-\u003edefine(string $name, string $value)` method of your `SwaggerGen` instance after\nstep 2 to define preprocessor variable names.\n\nThe following is a typical example:\n\n\t// Assuming you don't already have an autoloader\n\tspl_autoload_register(function ($classname) {\n\t\tinclude_once __DIR__ . $classname . '.php';\n\t});\n\n\t$SwaggerGen = new \\SwaggerGen\\SwaggerGen(\n\t\t$_SERVER['HTTP_HOST'],\n\t\tdirname($_SERVER['REQUEST_URI']),\n\t\t[__DIR__ . '/api']\n\t);\n\t$SwaggerGen-\u003edefine('admin');\t\t\t\t// admin = 1\n\t$SwaggerGen-\u003edefine('date', date('Y-m-d'));\t// date = \"2015-12-31\"\n\tif (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {\n\t\t$SwaggerGen-\u003edefine('windows');\t// windows = 1 (only if on Windows OS)\n\t}\n\t$swagger = $SwaggerGen-\u003egetSwagger(['Example.php']);\n\n\theader('Content-type: application/json');\n\techo json_encode($swagger);\n\n# SwaggerGen class\nThe only class you need to know about is the `SwaggerGen` class in the similarly\nnames `SwaggerGen` namespace.\n\n## `__construct($host = '', $basePath = '', $dirs = array())`\nCreate a new SwaggerGen object with the given `host` and `basePath` and provide\na set of `dirs` to use for scanning for classes that may be referenced\nfrom the sourcecode files you're about to scan.\n*\t`$host` should be the domain name, i.e. `www.example.com`.\n*\t`$basePath` should be the URL path to the root of the API, i.e. `/api/v1`.\n\n## `mixed getSwagger($files, $dirs = array(), $format = self::FORMAT_ARRAY)`\nGenerate Swagger/OpenAPI documentation by scanning the provided list of `files`.\nOptionally you can specify additional `dirs` to scan for class files and\nprovide a `format` to specify how you want to output the documentation.\n\nBy default, the documentation is output as an array, ready for encoding as JSON,\nYAML or for manual post-processing. The following formats are available as\nconstants of the `SwaggerGen` class.\n*\t`FORMAT_ARRAY` output the raw array.\n*\t`FORMAT_JSON` JSON-encoded output (mimetype `application/json`).\n*\t`FORMAT_JSON_PRETTY` JSON-encoded output with a human-friendly layout\n\t(mimetype `application/json`).\n*\t`FORMAT_YAML` YAML (UTF-8 character encoding) output\n\t(mimetype `application/x-yaml` (most common) or `text/yaml`).\n\n## `define($name, $value = 1)`\nDefine a value to be used by the preprocessor commands.\nBy default, it's value will be set to `1`.\n\n## `undefine($name)`\nUndefine a value, so it is no longer recognized by the preprocessor commands.\n\n# Creating documentation\nSwaggerGen takes a number of of source files and scans the comments for\ncommands it understands. The following is a short example of the type of\ncomments SwaggerGen understands:\n\n\t/*\n\t * @rest\\description SwaggerGen 2 Example API\n\t * @rest\\title Example API\n\t * @rest\\contact http://example.com Arthur D. Author\n\t * @rest\\license MIT\n\t * @rest\\security api_key apikey X-Api-Authentication header Authenticate using this fancy header\n\t * @rest\\require api_key\n\t */\n\n## Comments\nAll comments are parsed, this includes both doc-comments (`/** ... */`) and\nnormal comments, both single line (`// ...`) and multi-line (`/* ... */`).\n\nComments that are attached to functions, methods and classes. Any doc-comment\nimmediately preceeding a function, method or class will be attached to that\nfunction, method or class. Other comments will be attached to the function,\nmethod or class containing them. For instance, SwaggerGen comments within a\nfunction will be attached to that function.\n\n## Commands\n\nAll commands must be prefixed with `@rest\\` to distinguish between SwaggerGen\nstatements and normal comment statements and statements from other tools such\nas PHP-Documentor.\n\nAll commands are multi-line by default; any line(s) after the command that do\nnot start with an at-sign (`@`) are automatically appended to the command on the\nprevious line.\n\nYou can reference SwaggerGen documentation for other functions, methods or\nclasses by using the `uses` command. This command lets you specify an other\nfunction, method or class whose documentation to include.\n\nCommands are processed in the order in which they appear. This includes any\ndocumentation referenced with the `uses` command.\n\n## Contexts\nSwaggerGen uses a stack of contexts. Each context represents a certain part of\nthe Swagger documentation that will be generated. Each context supports a few\ncommands which hold meaning within that context.\n\nYou initially start at the Swagger context.\n\nYou can switch contexts using some of the commands available within the current\ncontext. In this manual, whenever a command switches the context, it is\nmarked using '\u0026rArr; Context name' at the end of the command syntax description.\n\nIf a command is not recognized in the current context, the context is removed\nfrom the top of the stack and the previous context tries to handle the command.\nIf no context is able to handle the command, SwaggerGen will report this as an\nerror.\n\n# Preprocessor commands\nSwaggerGen has a limited set of preprocessor statements to remove or change\nparts of the generated documentation at run-time.\n\nThe preprocessor statements are loosely based on the C/C++ preprocessors.\n\nThe work by defining values for variable names and checking whether or not a\nvariable name is defined or checking if a variables name has a specific value.\n\nSwaggerGen currently has no predefined variables, but you can define variables\nyourself by assigning them to the SwaggerGen parser before scanning starts.\n\nPreprocessor statments may be nested and are available for PHP and text.\n\n### `define` *`name [value]`*\nDefine a variable name and optionally assign a value to it.\n\n### `undef` *`name`*\nRemove the definition a variable name.\n\n### `if` *`name [value]`*\nIf the variable name is defined *and*, if provided, it's value is equal to\nthe specified value, then process all following SwaggerGen commands upto\nthe next preprocessor command.\nOtherwise, do not process those commands.\n\n### `ifdef` *`name`*\nIf the variable name is defined, then process all following SwaggerGen\ncommands upto the next preprocessor\tcommand.\nOtherwise, do not process those commands.\n\n### `ifndef` *`name`*\nIf the variable name is *not* defined, then process all following SwaggerGen\ncommands upto the next preprocessor\tcommand.\nOtherwise, do not process those commands.\n\n### `else`\nIf the previous `if...` or `elif` preprocessor command did *not* match,\nthen process all following SwaggerGen commands upto the next preprocessor\ncommand.\nOtherwise, do not process those commands.\n\n### `elif` *`name [value]`*\nIf the previous `if...` or `elif` preprocessor command did *not* match\n*and* if the variable name is defined *and*, if provided, it's value is\nequal to the specified value, then process all following SwaggerGen\ncommands upto the next preprocessor command.\nOtherwise, do not process those commands.\n\n### `endif`\nEnd the previous `if...`, `elif` or `else` preprocessor command's block of\nSwaggerGen commands.\n\n# SwaggerGen context and commands\nOrdered alphabetically for reference\n\nThe following commands can be used from within any context.\n\n### `uses` *`reference`*\nInclude a reference to another function, method or class.\n\nFor example:\n*\t`uses functionName`\n*\t`uses self::staticMethodName`\n*\t`uses $this-\u003emethodName`\n*\t`uses ClassName::staticMethodName`\n*\t`uses ClassName-\u003emethodName`\n\nSwaggerGen makes no distinction between the `self` and `this` or between\nthe static and dynamic `::` and `-\u003e`. These can be interchanged without\nany impact. Though it is advised to stick to the proper terms.\n\nClass inheritance is used if a method cannot be found within the indicated\nclass.\n\nalias: `see`\n\n### `x-[...]` *`data`*\nAdd a custom extension (starting with `x-`) to the current context.\n\nExtensions have no additional functionality and are treated as raw blobs of \ntext data.\n\n## BodyParameter\nRepresents a body parameter.\n\nFor a list of commands, read the chapter on  **Parameter definitions**.\nThe available command depend on the particular type.\n\n## Contact\nContains the contact information for the API.\n\n### `email` *`email`*\nSet the email address of the contact person.\n\n### `name` *`text ...`*\nSet the name of the contact person.\n\n### `url` *`email`*\nSet the URL where users can contact the maintainer(s).\n\n## Error\nRepresents a response with an error statuscode.\n\nSee the Response context for commands.\n\n## ExternalDocumentation\nContains an URL reference to additional documentation of the context which\ncreated this context.\n\n### `description` *`text ...`*\nSet the description text for this external documentation.\n\n### `url` *`url`*\nSet the URL to the external documentation.\n\n## Header\nRepresents a response header.\n\n### `description` *`text ...`*\nSet the description text of this response header.\n\n## Info\nContains non-technical information about the API, such as a description,\ncontact details and legal small-print.\n\n### `contact` *`[url] [email] [name ...]`* \u0026rArr; Contact\nSet the contactpoint or -person for this API.\nYou can specify the URL, email address and name in any order you want.\nThe URL and email address will be automatically detected, the name will\nconsist\tof all text remaining (properly separated with whitespace).\n\n### `description` *`text ...`*\n\tSet the description for the API.\n\n### `license` *`[url] [name ...]`* \u0026rArr; License\nSet the license for this API.\nYou can specify the URL in name in any order you want.\nIf you omit the URL, you can use any number of predefined names, which are\nautomatically expanded to a full URL, such as `gpl`, `gpl-2.1` or `bsd`.\n\n### `terms` *`text ...`*\nSet the text for the terms of service of this API.\n\nalias: `tos`, `termsofservice`\n\n### `title` *`text ...`*\nSet the API title.\n\n### `version` *`number`*\nSet the API version number.\n\n## License\nRepresents the name and URL of the license that applies to the API.\n\n### `name` *`text ...`*\nSet the name of the license.\nIf you haven't set a URL yet, a URL may be automatically set if it is one\nof a number of recognized license names, such as `mpl` or `apache-2`\n\n### `url` *`text ...`*\nSet the URL of the license.\n\n## Operation\nDescribes an operation; a call to a specifc path using a specific method.\n\n### `body`/`body?` *`definition name [description ...]`* \u0026rArr; BodyParameter\nAdd a new form Parameter to this operation.\n\nUse `body` to make the parameter required.\nUse `body?` (with a question mark) to make the parameter optional.\n\nSee the chapter on  **Parameter definitions** for a detailed\ndescription of all the possible definition formats.\n\n### `consumes` *`mime1 [mime2 ... mimeN]`*\nAdds mime types that this operation is able to understand.\nE.g. \"application/json\",  \"multipart/form-data\" or\n\"application/x-www-form-urlencoded\".\n\n### `deprecated`\nMark this operation as deprecated.\n\n### `description` *`text ...`*\nSet the long description of the operation.\n\n### `doc` *`url [description ...]`* \u0026rArr; ExternalDocumentation\nSet an URL pointing to more documentation.\n\nalias: `docs`\n\n### `error` *`statuscode [description]`* \u0026rArr; Error\nAdd a possible error statuscode that may be returned by this\noperation, including an optional description text.\n\nIf no description is given, the standard reason for the statuscode will\nbe used instead.\n\n### `errors` *`statuscode1 [statuscode2 ... statuscodeN]`*\nAdd several possible error statuscodes that may be returned by this\noperation.\n\n### `form`/`form?` *`definition name [description ...]`* \u0026rArr; Parameter\nAdd a new form Parameter to this operation.\n\nUse `form` to make the parameter required.\nUse `form?` (with a question mark) to make the parameter optional.\n\nSee the chapter on  **Parameter definitions** for a detailed\ndescription of all the possible definition formats.\n\n### `header`/`header?` *`definition name [description ...]`* \u0026rArr; Parameter\nAdd a new header Parameter to this operation.\n\nUse `header` to make the parameter required.\nUse `header?` (with a question mark) to make the parameter optional.\n\nSee the chapter on  **Parameter definitions** for a detailed\ndescription of all the possible definition formats.\n\n### `id` *`name`*\nSet an operation id for this operation.\n\n`name`  The ID name must be uniue among all operations in the document.\nIf you specify an ID that has already been set, an exception will be thrown.\n\n### `parameter` *`name`*\nAdd a new parameter by referencing the name of a globally defined parameter.\n\n`name`  The globally unique name of the parameter reference.\n\nalias: `param`\n\n### `path` *`definition name [description ...]`* \u0026rArr; Parameter\nAdd a new path Parameter to this operation.\n\n`path` parameters are always required; they cannot be optional.\n\nSee the chapter on  **Parameter definitions** for a detailed\ndescription of all the possible definition formats.\n\n### `produces` *`mime1 [mime2 ... mimeN]`*\nAdds mime types that this operation is able to produce.\nE.g. \"application/xml\" or \"application/json\".\n\n### `query`/`query?` *`definition name [description ...]`* \u0026rArr; Parameter\nAdd a new query Parameter to this operation.\n\nUse `query` to make the parameter required.\nUse `query?` (with a question mark) to make the parameter optional.\n\nSee the chapter on  **Parameter definitions** for a detailed\ndescription of all the possible definition formats.\n\n### `require` *`security1 [security2 ... securityN]`*\nSet the required security scheme(s) for this operation.\n\nSecurity schemes can be defined in the **Swagger** context.\n\n### `response` *`statuscode definition description`* \u0026rArr; Response\nAdds a possible response status code with a definition of the data that\nwill be returned. Though for error statuscodes you would typically use\nthe `error` or `errors` commands, you can use this command for those\nstatus codes as well, including a return definition.\n\nSee the chapter on  **Parameter definitions** for a detailed\ndescription of all the possible definition formats.\n\n### `response` *`reference statuscode`*\nReference a response definition.\n\nThe `reference` name must exist as a Response definition defined in the\n**Swagger** context.\n\nNote that this is one of two possible signatures for the `response` command.\n\n### `schemes` *`scheme1 [scheme2 ... schemeN]`*\nAdd any number of schemes to the operation.\n\n### `summary` *`text ...`*\nSet the a short summary description of the operation.\n\n### `tags` *`tag1 [tag2 ... tagN]`*\nAdd any number of tags to the operation.\n\n## Parameter\nRepresents either a form, query, header of path parameter.\n\nFor a list of commands, read the chapter on  **Parameter definitions**.\nThe available command depend on the particular type.\n\n## Path\nRepresents a URL endpoint or Path.\n\n### `operation` *`method [summary ...]`* \u0026rArr; Operation\nAdd a new operation to the most recently specified endpoint.\nMethod can be any one of `get`, `put`, `post`, `delete` or `patch`.\n\n### `description` *`text ...`*\nIf a tag exists, sets the description for the tag, otherwise to nothing.\n\n## Response\nRepresents a response.\n\n### `example` *`name content`*\nAdd an example to the response.\n\n`name` single-word (without spaces) name of the example. Unique per Response.\n\n`content` content of any type. Either a string, JSON object (quotes optional),\n`false`, `true`, `null` or a number (with or without floating point).\n\n### `header` *`type name [description]`* \u0026rArr; Header\nAdd a header to the response.\n\n`type` must be either `string`, `number`, `integer`, `boolean` or `array`.\n\n`name` must be a valid HTTP header name. I.e. `X-Rate-Limit-Limit`.\n\n## Schema\nRepresents a definitions of a type, such as an array.\n\n### `doc` *`url [description ...]`* \u0026rArr; ExternalDocumentation\nSet an URL pointing to more documentation.\n\nalias: `docs`\n\n### `title` *`text ...`*\nSet the title of this schema.\n\n### `description` *`description ...`*\nSet the description of this schema.\n\nFor a list of other commands, read the chapter on  **Parameter definitions**.\nThe available command depend on the particular type.\n\n## SecurityScheme\nRepresents a single way of authenticating the user/client to the server.\nYou specify the type of security scheme and it's settings using the `security`\ncommand from the Swagger context.\n\n### `description` *`text ...`*\nSet the description.\n\n### `scope` *`name [description ...]`*\nAdd a new oAuth2 scope name with optional description.\n\n## Swagger\nRepresents the entire API documentation.\nThis is the initial context for commands.\n\n### `consumes` *`mime1 [mime2] ... [mimeN]`*\nAdds mime types that the API is able to understand. E.g.\n\"application/json\",  \"multipart/form-data\" or\n\"application/x-www-form-urlencoded\".\n\nalias: `consume`\n\n### `contact` *`[url] [email] [name ...]`* \u0026rArr; Contact\nSet the contactpoint or -person for this API.\nYou can specify the URL, email address and name in any order you want.\nThe URL and email address will be automatically detected, the name will consist\nof all text remaining (properly separated with whitespace).\n\n### `definition` *`name` [type]* \u0026rArr; Schema\nStart definition of a Schema using the reference name specified. \n\nDefinitions can be specified as read only using exclamation point at the end of\nthe definition command. E.g. `definition! user` will create a user model that\nwill appear in GET responses and be omitted from POST, PUT, and PATCH requests.\n\nWhen no type is specified, `definition` creates an `object` definition. You can\nspecify `type` to create definitions for other types:\n\n    definition PositiveInteger integer[1,\u003e\n    \n    definition ArrayOfString array(string)\n\nSee the chapter on  **Parameter definitions** for a detailed description of all\nthe possible definition types.\n\nalias: `model` (for historical reasons)\n\n### `description` *`text ...`* \u0026rArr; Info\nSet the description for the API.\n\n### `doc` *`url [description ...]`* \u0026rArr; ExternalDocumentation\nSet an URL pointing to more documentation.\n\nalias: `docs`\n\n### `endpoint` *`/path [tag] [description ...]`* \u0026rArr; Path\nCreate an endpoint using the /path.\nIf tag is set, the endpoint will be assigned to the tag group of that name.\nIf a description is set, the description of the group will be set.\n\n### `license` *`[url] [name ...]`* \u0026rArr; License\nSet the license for this API.\nYou can specify the URL in name in any order you want.\nIf you omit the URL, you can use any number of predefined names, which are\nautomatically expanded to a full URL, such as `gpl`, `gpl-2.1`, `mit` or `bsd`.\n\n### `produces` *`mime1 [mime2] ... [mimeN]`*\nAdds mime types that the API is able to produce. E.g. \"application/xml\" or\n\"application/json\".\n\nalias: `produce`\n\n### `require` *`name [scopes]`*\nSet the required security scheme names.\nIf multiple names are given, they must all apply.\nIf an `oath2` scheme is specified, you may\n\n### `response` *`name definition description`* \u0026rArr; Response\nAdds a response definition with a schema definition of the data that will be\nreturned. You can omit the `definition` by specifying `null` instead.\n\nSee the chapter on  **Parameter definitions** for a detailed\ndescription of all the possible definition formats.\n\n### `schemes` *`scheme1 [scheme2] ... [schemeN]`*\nAdds protocol schemes. E.g. \"http\" or \"https\".\n\nalias: `scheme`\n\n### `security` *`name type [params ...]`* \u0026rArr; SecurityScheme\nDefine a security method, available to the API and individual operations.\nName can be any random name you choose. These names will be used to reference\nto the security shemes later on.\n\n`Type` must be either `basic`, `apikey` or `oauth2`.\nThe parameters depend on the type.\n\nFor `basic`, you can only specify a description text.\n\nFor `apikey`, you must first specify a name to use for the query parameter or\nheader, then use either `query` or `header` to set the type of apikey.\nOptionally followed by a description text.\n\nFor `oauth2`, you must set the flow type `implicit`, `password`, `application`\nor `accesscode`. For type `accesscode` you must specify two URL's, for\nauthorization and token respectively, for the other types only one URL is\nneeded. Optionally follow with a description text. You may need to add scopes\nusing the `scope` command afterwards.\n\n*\t`security` *`name`* `basic` *`[description ...]`*\n*\t`security` *`name`* `apikey` *`header-name`* `header` *`[description ...]`*\n*\t`security` *`name`* `apikey` *`query-variable`* `query` *`[description ...]`*\n*\t`security` *`name`* `oauth2 implicit` *`auth-url [description ...]`*\n*\t`security` *`name`* `oauth2 password` *`token-url [description ...]`*\n*\t`security` *`name`* `oauth2 application` *`token-url [description ...]`*\n*\t`security` *`name`* `oauth2 accesscode` *`auth-url token-url [description ...]`*\n\n### `tag` *`tag [description ...]`* \u0026rArr; Tag\nSpecifies a tag definition; essentially the category in which an endpoint path\nwill be grouped together.\n\nalias: `api` (for historical reasons).\n\n### `terms` *`text ...`* \u0026rArr; Info\nSet the text for the terms of service of this API.\n\nalias: `tos`, `termsofservice`\n\n### `title` *`text ...`* \u0026rArr; Info\nSet the API title.\n\n### `version` *`number`* \u0026rArr; Info\nSet the API version number.\n\n## Tag\nA tag is used to group paths and operations together in logical categories.\n\n### `description` *`text ...`*\nSet the description.\n\n### `doc` *`url [description ...]`* \u0026rArr; ExternalDocumentation\nSet an URL pointing to more documentation.\n\nalias: `docs`\n\n# Parameter definitions\n\nAll parameters can handle the `example` command:\n\n### Commands\n*\t**`example` *content*** Set the example content of any type.\nEither a string, JSON object (quotes optional), `false`, `true`, `null` or a\nnumber (with or without floating point).\n\n## string, byte, binary, password\nRepresents a text.\n\n\ttype(pattern)[0,\u003e=default\n\n*\ttype: `string` or `binary`,\n*\trange: [min,max].\n\tUse `[` or `]` for inclusive and `\u003c` or `\u003e` for\texclusive.\n\tEmpty `min` value means zero.\n\tEmpty `max` value means infinity.\n*\tdefault: any valid text not containing whitespace.\n\n### Commands\n*\t**`default` *value*** Set the default value.\n*\t**`enum` *value1 value2 ... valueN*** Set or add allowed values.\n\n### Examples\n*\t**`string`** A simple text field.\n*\t**`string(^[a-z]{2}-[A-Z]{2}$)`** String matching ISO \"ll-CC\" locale.\n*\t**`string[,256\u003e=red`** A text of at most 255 characters, default to \"red\".\n*\t**`binary[1,8]`** Upto 8 binary digits, requiring atleast one.\n\n\n## int32 (integer, int), int64 (long)\nRepresents numbers without decimals.\n\n\ttype[0,\u003e=default\n\n*\ttype: `integer`, `int`, `int32`, `long` or `int64`.\n*\trange: [min,max].\n\tUse `[` or `]` for inclusive and `\u003c` or `\u003e` for\texclusive.\n\tEmpty `min` or `max` values means infinity.\n*\tdefault: any valid integer.\n\n### Commands\n*\t**`default` *value*** Set the default value.\n*\t**`enum` *value1 value2 ... valueN*** Set or add allowed values.\n*\t**`step` *value*** Set the stepsize between numbers.\n\n### Examples\n*\t**`int`** 32-bit integer without a default or limited range.\n*\t**`long\u003c,0\u003e`** 64-bit negative integers only.\n*\t**`integer[0,\u003e=100`** 32-bit positive integer or zero, default to 100.\n\n\n## float, double\nRepresents floating point numbers (with decimals).\n\n\ttype[0,\u003e=default\n\n*\ttype: `float` or `double`\n*\trange: [min,max].\n\tUse `[` or `]` for inclusive and `\u003c` or `\u003e` for\texclusive.\n\tEmpty `min` or `max` values means infinity.\n*\tdefault: any valid integer.\n\n### Commands\n*\t**`default` *value*** Set the default value.\n*\t**`enum` *value1 value2 ... valueN*** Set or add allowed values.\n*\t**`step` *value*** Set the stepsize between numbers.\n\n### Examples\n*\t**`float`** 32-bit floating point number without a default or limited range.\n*\t**`double\u003c,1\u003e`** 64-bit floating point numbers upto (but not including) 1.\n*\t**`float\u003c0,\u003e=0.1`** 32-bit positive numbers, excluding 0, default to 0.1.\n\n\n## boolean (bool)\nA true/false choice.\n\n\ttype=default\n\n*\ttype: `boolean` or `bool`.\n*\tdefault: `true`, `false`, 1 (true) or 0 (false).\n\n### Commands\n*\t**`default` *value*** Set the default value.\n\n### Examples\n*\t**`boolean`** A basic boolean.\n*\t**`bool=true`** A boolean, default to true.\n\n\n## date, date-time (datetime)\nSpecial type of string which is limited to dates only\n\n\ttype=default\n\n*\ttype: `date`, `date-time` or `datetime`,\n*\tdefault: Any valid date format recognized by the [PHP DateTime object](http://php.net/manual/en/datetime.formats.php).\n\n### Commands\n*\t**`default` *date*** Set the default value.\n\n### Examples\n*\t**`date`** A simple date\n*\t**`datetime=2015-12-31T12:34:56Z`** Date and time set to a default without\n\ta timezone offset.\n*\t**`datetime=2015-12-31T12:34:56.001+01:00`** Date and time set to a default\n\tvalue with fractional seconds and a timezone offset.\n\n## csv (array), ssv, tsv, pipes, multi\nList of items\n\n\ttype(definition)[0,\u003e\n\nAlternative short-hand notation for `array` lists:\n\n\t[definition][0,\u003e\n\n*\ttype: `csv`, `array`, `ssv`, `tsv`, `pipes`, or `multi`.\n*\trange: [min,max].\n\tUse `[` or `]` for inclusive and `\u003c` or `\u003e` for\texclusive.\n\tEmpty `min` value means zero.\n\tEmpty `max` value means infinity.\n*\tdefault: any valid text not containing whitespace.\n*\tdefinition: a definition of the type of the items in the list. It is possible to\n\tdefine lists as items, creating multidimensional arrays.\n\n### Commands\n*\t**`min` *value*** Set the minimum number of items required.\n*\t**`max` *value*** Set the maximum number of items allowed.\n*\t**`items` *definition*** Set the definition of the items in this list.\n\n### Types\n*\t**`csv`** Comma (`,`) separated. I.e. `red,green,blue`. Alias: `array`.\n*\t**`ssv`** Space ( ) separated. I.e. `red green blue`.\n*\t**`tsv`** Tab-separated. I.e. `red\tgreen\tblue`.\n*\t**`pipes`** Pipe (`|`) separated. I.e. `red|green|blue`.\n*\t**`multi`** query-string formatted. I.e. `color=red\u0026color=green\u0026color=blue`.\n\tThis choice is only available for `form` and `query` parameters.\n\n### Examples\n*\t**`csv(string)`** A comma-separated list of strings.\n\n## file\nA file.\n\n\tfile\n\nNo further definition is possible. There are no command.\n\n### Examples\n*\t**`file`** A file.\n\n## object\nObject with properties. Typically used as key-value map\n\n\tobject(definition)[0,\u003e\n\nAlternative short-hand notation:\n\n\t{definition}[0,\u003e\n\n*\ttype: `object`.\n*\trange: [min,max].\n\tUse `[` or `]` for inclusive and `\u003c` or `\u003e` for\texclusive.\n\tEmpty `min` value means zero properties (no minimum).\n\tEmpty `max` value means infinite properties (no maximum).\n*\tdefinition: a comma-separated list of property definitions in the form of\n\t`key:definition`, where `key` can be any sequence of characters except `:` or\n\t`?` or `!`. The `?` means that key is optional. The `!` means the key is read only. \n\tRead only implies optional as well.\n\n### Commands\n*\t**`min` *value*** Set the minimum number of items required.\n*\t**`max` *value*** Set the maximum number of items allowed.\n*\t**`property` *definition name*** Add a required property.\n*\t**`property?` *definition name*** Add an optional property.\n*   **`property!` *definition name*** Add a read only property.\n*   **`discriminator` *propertyName*** Sets the property as a discriminator.\n\tThe property must be required (could not be read only nor optional), but\n\tyou can define it later.\n\n### Examples\n*\t**`object(age:int[18,25\u003e)`** An object containing a single key `age` with\n\tan integer value greater or equal to 18 and less than 25.\n*\t**`object(age:int,name?:string[2,\u003e)`** An object containing an `age` and an\n\toptional `name` string, where the value must be atleast two characters\n\tlong.\n*\t**`object()[4,8]`** An object containing four to eight unknown properties.\n\n## allof\nIntersection type (data must satisfy all base types). May be used for type\ncomposition or to implement inheritance (in conjunction with `discriminator`).\nCould also be used to refine the constraints imposed by the base type.\n\n    allof(definition)\n\n*\tdefinition: a comma-separated list of base types, either as inline\n\tdefinitions or references to another definition\n\n### Commands\n*   **`item` *type*** Add the type to the list of allOf types\n\n### Examples\n*   **`allOf(DataModel,IdModel)`** type composition: effectively creates\n\tDataWithId type.\n*   **`allOf(ModelWithOptionalName,object(name:string))`** type refinement:\n\teffectively makes `name` property required.\n\n## enum\nSpecial type of string which is limited to one of a number of predefined values.\n\n\tenum(value1,value1,...,valueN)=default\n\n*\tvalues: any text not containing whitespace or commas.\n*\tdefault: any of the specified texts.\n\n### Commands\nSee string.\n\n### Examples\n*\t**`enum(red,green,blue)=red`** A string containing either \"red\", \"green\" or\n\t\"blue\", default to \"red\".\n\n## uuid\nSpecial type of string which accepts\n[RFC 4122](https://www.ietf.org/rfc/rfc4122.txt) compliant Universally Unique\nIDentifier (UUID) strings. The default value is validated to ensure only valid\nUUID's are specified.\n\n\tuuid=default\n\n*\tdefault: any of the specified texts.\n\n### Commands\nSee string.\n\n### Examples\n*\t**`uuid=123e4567-e89b-12d3-a456-426655440000`** A uuid string, default to\n\tthe uuid \"123e4567-e89b-12d3-a456-426655440000\".\n\n## refobject\nReference to a globally defined `definition` (a.k.a. `model`) object.\n\n\trefobject(definitionName)\n\nor\n\n\tdefinitionName\n\n*\tdefinitionName: the name of the globally defined `definition`.\n\n### Examples\n*\t**`refobject(Address)`** Reference the a globally defined model named\n\t`Address`.\n*\t**`Address`** Reference the a globally defined model named\n\t`Address`.\n\n### Notes\nUsually, using the definition name alone is good enough.\nUse `refobject(...)` if you are using a name which is also used as a builtin\nparameter type, such as `string` or `object`.\nIt is best practice to start all definition names with an upper case character\n(i.e. `Address`).\nUsing `refobject(...)` also offers the safest forward-compatible strategy if\nyou do not start definition names with upper case (i.e. `address`).\n\n# Appendices\n## Mime types\nSome commands, such as `consumes` and `produces` take mime types as arguments.\nInstead of specifying the full mime types, you can any of the following\npredefined shorthands (case insensitive):\n\n\tfileform\tmultipart/form-data\n\tform\t\tapplication/x-www-form-urlencoded\n\tjson\t\tapplication/json\n\ttext\t\ttext/plain\n\tutf8\t\ttext/plain; charset=utf-8\n\tyml\t\t\tapplication/x-yaml\n\tyaml\t\tapplication/x-yaml\n\tphp\t\t\ttext/x-php\n\txml\t\t\ttext/xml\n\n## Licenses\nA selection of shorthands are available for licenses.\nIf you want another license added to it, please submit an issue or create a\npull request. The file you want to edit is `/SwaggerGen/Swagger/License.php`.\n\nThese are the license shorthands currently available:\n\n\tartistic-1.0\thttp://opensource.org/licenses/artistic-license-1.0\n\tartistic-1\t\thttp://opensource.org/licenses/artistic-license-1.0\n\tartistic-2.0\thttp://opensource.org/licenses/artistic-license-2.0\n\tartistic-2\t\thttp://opensource.org/licenses/artistic-license-2.0\n\tartistic\t\thttp://opensource.org/licenses/artistic-license-2.0\n\tbsd-new\t\t\thttps://opensource.org/licenses/BSD-3-Clause\n\tbsd-3\t\t\thttps://opensource.org/licenses/BSD-3-Clause\n\tbsd-2\t\t\thttps://opensource.org/licenses/BSD-2-Clause\n\tbsd\t\t\t\thttps://opensource.org/licenses/BSD-2-Clause\n\tepl-1.0\t\t\thttp://www.eclipse.org/legal/epl-v10.html\n\tepl-1\t\t\thttp://www.eclipse.org/legal/epl-v10.html\n\tepl\t\t\t\thttp://www.eclipse.org/legal/epl-v10.html\n\tapache-2.0\t\thttp://www.apache.org/licenses/LICENSE-2.0.html\n\tapache-2\t\thttp://www.apache.org/licenses/LICENSE-2.0.html\n\tapache\t\t\thttp://www.apache.org/licenses/LICENSE-2.0.html\n\tgpl-1.0\t\t\thttps://www.gnu.org/licenses/gpl-1.0.html\n\tgpl-1\t\t\thttps://www.gnu.org/licenses/gpl-1.0.html\n\tgpl-2.0\t\t\thttps://www.gnu.org/licenses/gpl-2.0.html\n\tgpl-2\t\t\thttps://www.gnu.org/licenses/gpl-2.0.html\n\tgpl-3.0\t\t\thttp://www.gnu.org/licenses/gpl-3.0.html\n\tgpl-3\t\t\thttp://www.gnu.org/licenses/gpl-3.0.html\n\tgpl\t\t\t\thttp://www.gnu.org/licenses/gpl-3.0.html\n\tlgpl-2.0\t\thttp://www.gnu.org/licenses/lgpl-2.0.html\n\tlgpl-2.1\t\thttp://www.gnu.org/licenses/lgpl-2.1.html\n\tlgpl-2\t\t\thttp://www.gnu.org/licenses/lgpl-2.1.html\n\tlgpl-3.0\t\thttp://www.gnu.org/licenses/lgpl-3.0.html\n\tlgpl-3\t\t\thttp://www.gnu.org/licenses/lgpl-3.0.html\n\tlgpl\t\t\thttp://www.gnu.org/licenses/lgpl-3.0.html\n\tmit\t\t\t\thttp://opensource.org/licenses/MIT\n\tmpl-1.1\t\t\thttps://www.mozilla.org/en-US/MPL/1.1/\n\tmpl-1\t\t\thttps://www.mozilla.org/en-US/MPL/1.1/\n\tmpl-2.0\t\t\thttps://www.mozilla.org/en-US/MPL/\n\tmpl-2\t\t\thttps://www.mozilla.org/en-US/MPL/\n\tmpl\t\t\t\thttps://www.mozilla.org/en-US/MPL/\n\tmspl\t\t\thttps://msdn.microsoft.com/en-us/library/ff648068.aspx\n\n\n# Example\nTo view an example of Swagger documentation generated with SwaggerGen, visit\nthe [Example API documentation](./example/docs/).\n\nThe following is a fragment of code from this example:\n\n\t/**\n\t * @rest\\endpoint /user/{username}\n\t * @rest\\method GET Get a list of all users\n\t * @rest\\path String username Name of the user\n\t * @rest\\see self::request\n\t */\n\tprivate function getUser($name)\n\t{\n\t\t/*\n\t\t * @rest\\model User\n\t\t * @rest\\property int age Age of the user in years\n\t\t * @rest\\property int height Height of the user in centimeters\n\t\t */\n\t\treturn $this-\u003edata['users'][$name]; // @rest\\response OK object(age:int[0,100\u003e,height:float) User\n\t}\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvanderlee%2Fphpswaggergen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvanderlee%2Fphpswaggergen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvanderlee%2Fphpswaggergen/lists"}