{"id":41512707,"url":"https://github.com/digit-soft/laravel-swagger-generator","last_synced_at":"2026-01-23T20:09:24.091Z","repository":{"id":56968690,"uuid":"164073911","full_name":"digit-soft/laravel-swagger-generator","owner":"digit-soft","description":"Swagger docs (OA 3.0) generator for Laravel","archived":false,"fork":false,"pushed_at":"2025-05-26T06:39:10.000Z","size":234,"stargazers_count":14,"open_issues_count":3,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-09-14T21:40:47.142Z","etag":null,"topics":["annotations","phpdoc","swagger","swagger-generator"],"latest_commit_sha":null,"homepage":"","language":"PHP","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/digit-soft.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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,"zenodo":null}},"created_at":"2019-01-04T07:30:50.000Z","updated_at":"2025-05-26T06:38:59.000Z","dependencies_parsed_at":"2023-02-13T20:32:00.761Z","dependency_job_id":"3c4c99b3-bbf8-4007-bb16-5106c8727b2a","html_url":"https://github.com/digit-soft/laravel-swagger-generator","commit_stats":{"total_commits":194,"total_committers":1,"mean_commits":194.0,"dds":0.0,"last_synced_commit":"1e79a7d3d86c1dd781dd2c4373efa7913d9d5136"},"previous_names":[],"tags_count":67,"template":false,"template_full_name":null,"purl":"pkg:github/digit-soft/laravel-swagger-generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digit-soft%2Flaravel-swagger-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digit-soft%2Flaravel-swagger-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digit-soft%2Flaravel-swagger-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digit-soft%2Flaravel-swagger-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/digit-soft","download_url":"https://codeload.github.com/digit-soft/laravel-swagger-generator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digit-soft%2Flaravel-swagger-generator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28699372,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T17:25:48.045Z","status":"ssl_error","status_checked_at":"2026-01-23T17:25:47.153Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["annotations","phpdoc","swagger","swagger-generator"],"created_at":"2026-01-23T20:09:23.317Z","updated_at":"2026-01-23T20:09:24.084Z","avatar_url":"https://github.com/digit-soft.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Swagger generator\nThis package is made to automate API documentation for Swagger (Open Auth 3.0)\n\n## Publish config\n```bash\nphp artisan vendor:publish --provider=\"DigitSoft\\Swagger\\SwaggerGeneratorServiceProvider\" --tag=\"config\"\n```\n\n## Usage\nTo generate doc file (YML) run following command:\n```bash\nphp artisan swagger:generate\n```\nTo see problems with generation use `diagnose` mode, where file will not be generated, only helpful information will be printed.\n```bash\nphp artisan swagger:generate --diagnose\n```\n\n## Describing your code\n### Annotations list\n\n| Name                  | Description                           | Places to use |\n|-----------------------|---------------------------------------|---------------|\n| @OA\\Response          | Describes raw response                | Controller method |\n| @OA\\ResponseParam     | Describes response parameter in `Response` | Inside `{}` of `Response` annotation |\n| @OA\\ResponseClass     | Describes response as class object    | Controller method |\n| @OA\\ResponseError     | Describes error response (shortcut)   | Controller method |\n| @OA\\RequestBody       | Describes request body                | `FormRequest` class |\n| @OA\\RequestBodyJson   | Describes request body with `application\\json` content type | `FormRequest` class |\n| @OA\\RequestParam      | Describes request body parameter      | Used as argument in `@OA\\RequestBody` annotation |\n| @OA\\RequestParamArray | Describes request body parameter. Shortcut for array type parameter | Used as argument in `@OA\\RequestBody` annotation |\n| @OA\\Parameter         | Describes route parameter             | Controller method, Controller class |\n| @OA\\Property          | Describes class property              | Class used for response |\n| @OA\\PropertyIgnore    | Mark class property as ignored        | Class used for response |\n| @OA\\Secured           | Describes route as secured            | Controller method |\n| @OA\\Tag               | Describes route tags                  | Controller method, Controller class |\n| @OA\\Ignore            | Marks whole controller or it's action as ignored | Controller method, Controller class |\n| @OA\\Symlink           | Describes symlink to another class    | Class used for response |\n\n### Responses\nResponses are parsed only if explicitly documented by `@Annotation`. It must be placed in PHPDoc of **controller method** that route use.\nRAW response:\n```php\n/**\n * Controller method PHPDoc\n *\n * @OA\\Response(true,contentType=\"application/json\",description=\"Boolean response\")\n *\n * @param Request $request\n * @return \\Illuminate\\Http\\JsonResponse\n */\n```\nJSON RAW response:\n```php\n/**\n * Controller method PHPDoc\n *\n * @OA\\ResponseJson({\"key\":\"value\"},status=201,description=\"User data response\")\n *\n * @param Request $request\n * @return \\Illuminate\\Http\\JsonResponse\n */\n```\nor\n```php\n/**\n * Controller method PHPDoc\n *\n * @OA\\ResponseJson({\n *      @OA\\ResponseParam(\"key\",type=\"string\",example=\"value\",description=\"Some parameter\"),\n * },status=201,description=\"User data response\")\n *\n * @param Request $request\n * @return \\Illuminate\\Http\\JsonResponse\n */\n```\nResponse from class properties:\n```php\n/**\n * Controller method PHPDoc\n *\n * @OA\\ResponseClass(\"App\\User\",description=\"User model response\")\n *\n * @param Request $request\n * @return \\Illuminate\\Http\\JsonResponse\n */\n```\nIn example above response data will be parsed from `App\\User` PHPDoc.\n1. `@property` descriptions (property name, type and description)\n2. `@property-read` descriptions (if set `with` property in `ResponseClass` annotation)\n3. `@OA\\Property` annotations (property name, type, description, example etc.)\n\n`@OA\\ResponseClass` use cases,\nfirst is standard use but with additional properties\n```php\n/**\n * @OA\\ResponseClass(\"App\\User\",with={\"profile\"},status=201)\n */\n```\nAs items list\n```php\n/**\n * @OA\\ResponseClass(\"App\\User\",asList=true)\n */\n```\nAs paged items list\n```php\n/**\n * @OA\\ResponseClass(\"App\\User\",asPagedList=true)\n */\n```\n\nError responses\n```php\n/**\n * @OA\\ResponseError(403) // Forbidden\n * @OA\\ResponseError(404) // Not found\n * @OA\\ResponseError(422) // Validation error\n */\n```\n### Request bodies\nRequest data is parsed from `::rules()` method of `FormRequest` class, that used in controller method for the route and it's annotations (`@OA\\RequestBody`, `@OA\\RequestBodyJson`,  `@OA\\RequestParam`).\nFrom `::rules()` method we can obtain only name and type of parameter and suggest some example,\nbut if you want fully describe parameters of request body you must place appropriate annotations in `FormRequest` class for route.\n#### Examples\n```php\n/**\n * @OA\\RequestBodyJson({\n *   @OA\\RequestParam(\"first_name\",type=\"string\",description=\"User name\"),\n *   @OA\\RequestParam(\"email\",type=\"string\",description=\"User email\"),\n *   @OA\\RequestParamArray(\"phones\",items=\"string\",description=\"User phones array\"),\n * })\n */\n```\n### Tags\nTags can be defined in Controller class or method that route uses.\nDo not use space ` ` in tag names, link with such tag name will be broken in Swagger UI, so better idea to use dash `-` or underscore `_`, or even just a `CamelCased` tag names.\nTags defined in controller will be applied to ALL controller methods.\n```php\n/**\n * @OA\\Tag(\"Tag-name\")\n */\n```\n### Secured\nThis annotation is used to mark route as `secured`, and tells to swagger, that you must provide valid user credentials to access this route.\nPlace it in controller method.\n```php\n/**\n * @OA\\Secured()\n */\n```\n### Property\n`@OA\\Property` annotation is used to describe class properties as an alternative or addition to PHPDoc `@property`.\nYou can place example of property (if property is an associative array for example)\nor fully describe property if you dont want to place `@property` declaration for it.\n```php\n/**\n * @OA\\Property(\"notification_settings\",type=\"object\",example={\"marketing\":false,\"user_actions\":true},description=\"User notification settings\")\n */\n```\n### PropertyIgnore\n`@OA\\PropertyIgnore` annotation is used to remove given property from object description.\n```php\n/**\n * @OA\\PropertyIgnore(\"property_name\")\n */\n```\n### Symlink\nThis annotation can be used to describe symlink to another class (e.g. for response). All data in class PHPDoc in which it appears will be ignored.\n\nYou must use full namespace of annotations, e.g. `OA\\Property`.\n\nBesides, you can import a namespace for better code completion as in example beyond.\n```php\nnamespace App\\Models;\n\nuse OA;\n\n/**\n * Test model class\n *\n * @OA\\Property(\"id\",type=\"integer\",description=\"Primary key\")\n *\n * @property string $name String name\n */\nclass TestModel {}\n```\n\n### More\nThere is abstract annotation class `OA\\DescriptionExtender`, you can use it for your own annotations, those must add some information to route's description.\n\nExample is bellow.\n\n```php\n\u003c?php\n\nnamespace App\\Components\\Annotations\\Swagger;\n\nuse OA\\DescriptionExtender;\nuse Doctrine\\Common\\Annotations\\Annotation;\nuse Doctrine\\Common\\Annotations\\Annotation\\{Attribute, Attributes};\n\n/**\n * Describes needed permission\n * @Annotation\n * @Attributes({\n *  @Attribute(\"value\",type=\"string\"),\n * })\n * @package App\\Components\\Annotations\\Swagger\n */\nclass Permission extends DescriptionExtender\n{\n    /**\n     * @inheritdoc\n     */\n    public function __toString()\n    {\n        return '**Permission:** `' . $this-\u003evalue . '`';\n    }\n}\n```\nYou can use annotation from example:\n```php\n\u003c?php\nuse App\\Components\\Annotations\\Swagger as SWA;\n\n\n/**\n * Controller method PHPDoc\n *\n * @OA\\ResponseClass(\"App\\User\",description=\"User model response\")\n * @SWA\\Permission(\"articles.can-update\")\n *\n * @param Request $request\n * @return \\Illuminate\\Http\\JsonResponse\n */\n```\nand it will add following text into route's description\n```\nDescription for route goes here...bla-bla-bla...\n\n**Permission:** `articles.can-update`\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigit-soft%2Flaravel-swagger-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigit-soft%2Flaravel-swagger-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigit-soft%2Flaravel-swagger-generator/lists"}