PHPackages davmixcool/lumen-apidoc-generator - 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. [API Development](/categories/api) 4. / 5. davmixcool/lumen-apidoc-generator ActiveLibrary[API Development](/categories/api) davmixcool/lumen-apidoc-generator ================================= Generate beautiful API documentation using Dingo router from your Lumen application 1.0.0(7y ago)173.1k5MITPHPPHP >=5.5.0 Since Aug 27Pushed 7y ago4 watchersCompare [ Source](https://github.com/davmixcool/lumen-apidoc-generator)[ Packagist](https://packagist.org/packages/davmixcool/lumen-apidoc-generator)[ Docs](http://github.com/davmixcool/lumen-apidoc-generator)[ RSS](/packages/davmixcool-lumen-apidoc-generator/feed)WikiDiscussions master Synced yesterday READMEChangelogDependencies (10)Versions (2)Used By (0) Lumen API Documentation Generator --------------------------------- [](#lumen-api-documentation-generator) Automatically generate your API documentation using Dingo router in your Lumen app. Take a look at the [example documentation](http://marcelpociot.de/whiteboard/). `php artisan api:generate --router="dingo" --routePrefix="v1"` [![GitHub license](https://camo.githubusercontent.com/2cedd7de439c5d56b314fbe2064b456229c07bd570dd37a98fd0f05af2546f7d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6461766d6978636f6f6c2f6c756d656e2d617069646f632d67656e657261746f722e737667)](https://github.com/davmixcool/lumen-apidoc-generator/blob/master/LICENSE.md)[![StyleCI](https://camo.githubusercontent.com/bc0002baa65e566617a950bdab9499c5698fe4cfbd49bd1affd8cd830a651533/68747470733a2f2f7374796c6563692e696f2f7265706f732f35373939393239352f736869656c643f7374796c653d666c6174)](https://styleci.io/repos/57999295)[![GitHub issues](https://camo.githubusercontent.com/010eeedbb0d180cdde898c1f4143121b307a83cd63ad445d4f0eaad41a3b9ae8/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f6461766d6978636f6f6c2f6c756d656e2d617069646f632d67656e657261746f722e737667)](https://github.com/davmixcool/lumen-apidoc-generator/issues) Installation ------------ [](#installation) Require this package with composer using the following command: ``` $ composer require davmixcool/lumen-apidoc-generator ``` Go to your `bootstrap/app.php` and register the service provider: ``` $app->register(Davmixcool\ApiDoc\ApiDocGeneratorServiceProvider::class); ``` Usage ----- [](#usage) To generate your API documentation, use the `api:generate` artisan command. ``` $ php artisan api:generate --router="dingo" --routePrefix="v1" ``` This command will scan your applications routes for the URIs matching `v1/*` and will parse these controller methods and validate rules. For example: ``` $api = app('Dingo\Api\Routing\Router'); $api->version('v1', function ($api) { $api->group(['namespace' => 'App\Http\Controllers'], function ($api) { // Custom get route added to standard Resource $api->get('example/get', 'ExampleController@foo'); //Custom post route added to standard Resource $api->post('example/post', 'ExampleController@save'); }); }); ``` ### Available command options: [](#available-command-options) OptionDescription`output` The output path used for the generated documentation. Default: `public/docs``routePrefix`The route prefix to use for generation - `*` can be used as a wildcard`routes`The route names to use for generation - Required if no routePrefix is provided`middleware`The middlewares to use for generation`noResponseCalls`Disable API response calls`noPostmanCollection`Disable Postman collection creation`useMiddlewares`Use all configured route middlewares (Needed for Laravel 5.3 `SubstituteBindings` middleware)`actAsUserId`The user ID to use for authenticated API response calls`router`The router to use, when processing the route files (can be Laravel or Dingo - defaults to Laravel)`bindings`List of route bindings that should be replaced when trying to retrieve route results. Syntax format: `binding\_one,id`force`Force the re-generation of existing/modified API routes`header`Custom HTTP headers to add to the example requests. Separate the header name and value with ":". For example: `--header="Authorization: CustomToken"``domain`Custom domain to get response. Domain must end with "/". Will be ignore if `noResponseCalls` set to TRUECustomisation or translation. ----------------------------- [](#customisation-or-translation) By default, this package returns the descriptions in english. You can publish the packages language files, to customise and translate the documentation output. ``` $ php artisan vendor:publish ``` After the files are published you can customise view, styles or translate the descriptions in the language you want by renaming the `en` folder and editing the files in `public/vendor/apidoc/resources/lang`. ### How does it work? [](#how-does-it-work) This package uses these resources to generate the API documentation: #### Controller doc block [](#controller-doc-block) This package uses the HTTP controller doc blocks to create a table of contents and show descriptions for your API methods. Using `@resource` in a doc block prior to each controller is useful as it creates a Group within the API documentation for all methods defined in that controller (rather than listing every method in a single list for all your controllers), but using `@resource` is not required. The short description after the `@resource` should be unique to allow anchor tags to navigate to this section. A longer description can be included below. Above each method within the controller you wish to include in your API documentation you should have a doc block. This should include a unique short description as the first entry. An optional second entry can be added with further information. Both descriptions will appear in the API documentation in a different format as shown below. ``` /** * @resource Example * * Longer description */ class ExampleController extends Controller { /** * This is the short description [and should be unique as anchor tags link to this in navigation menu] * * This can be an optional longer description of your API call, used within the documentation. * */ public function foo(){ } ``` **Result:** [![Doc block result](https://camo.githubusercontent.com/5acbb8764bb5b4b40504968cf5618fc0e2f71f006d4cb712bb0773c219d7bd16/687474703a2f2f6865616473717561726564736f6674776172652e636f2e756b2f696d616765732f6170695f67656e657261746f725f646f63626c6f636b2e706e67)](https://camo.githubusercontent.com/5acbb8764bb5b4b40504968cf5618fc0e2f71f006d4cb712bb0773c219d7bd16/687474703a2f2f6865616473717561726564736f6674776172652e636f2e756b2f696d616765732f6170695f67656e657261746f725f646f63626c6f636b2e706e67) #### Validation rules [](#validation-rules) To display a list of valid parameters, your API methods accepts, this package uses Lumen Validation Helper Method [Validation](https://lumen.laravel.com/docs/5.6/validation). ``` $this->validate($request,[ 'title' => 'required|max:255', 'body' => 'required', 'type' => 'in:foo,bar', 'thumbnail' => 'required_if:type,foo|image', ]); ``` **Result:** [![Form Request](https://camo.githubusercontent.com/bbfde84c1a88d740a02896f51757e519f987fade9af9cdf633c92aff28f522c6/687474703a2f2f6d617263656c706f63696f742e64652f646f63756d656e74617269616e2f666f726d5f726571756573742e706e67)](https://camo.githubusercontent.com/bbfde84c1a88d740a02896f51757e519f987fade9af9cdf633c92aff28f522c6/687474703a2f2f6d617263656c706f63696f742e64652f646f63756d656e74617269616e2f666f726d5f726571756573742e706e67) #### Controller method doc block [](#controller-method-doc-block) It is possible to override the results for the response. This will also show the responses for other request methods then GET. #### @transformer [](#transformer) With the transformer you can define the transformer that is used for the result of the method. It will try the next parts to get a result if it can find the transformer. The first successfull will be used. 1. Check if there is a transformermodel tag to define the model 2. Get a model from the modelfactory 3. If the parameter is a Eloquent model it will load the first from the database. 4. A new instance from the class ``` /** * @transformer \Davmixcool\ApiDoc\Tests\Fixtures\TestTransformer */ public function transformerTag() { return ''; } ``` #### @transformercollection [](#transformercollection) This is the same idea as the @tranformer tag with one different, instead of the return of an item, it will generate the return of a set with two items ``` /** * @transformercollection \Davmixcool\ApiDoc\Tests\Fixtures\TestTransformer */ public function transformerCollectionTag() { return ''; } ``` #### @transformermodel [](#transformermodel) The @transformermodel tag is needed for PHP 5.\* to get the model. For PHP 7 is it optional to specify the model that is used for the transformer. #### @response [](#response) If you expliciet want to specify the result of a function you can set it in the docblock ``` /** * @response { * data: [], *} */ public function responseTag() { return ''; } ``` #### API responses [](#api-responses) If your API route accepts a `GET` method, this package tries to call the API route with all middleware disabled to fetch an example API response. If your API needs an authenticated user, you can use the `actAsUserId` option to specify a user ID that will be used for making these API calls: ``` $ php artisan api:generate --router="dingo" --routePrefix="v1" --actAsUserId=1 ``` If you don't want to automatically perform API response calls, use the `noResponseCalls` option. ``` $ php artisan api:generate --router="dingo" --routePrefix="v1" --noResponseCalls ``` > Note: The example API responses work best with seeded data. #### Postman collections [](#postman-collections) The generator automatically creates a Postman collection file, which you can import to use within your [Postman App](https://www.getpostman.com/apps) for even simpler API testing and usage. If you don't want to create a Postman collection, use the `--noPostmanCollection` option, when generating the API documentation. ``` 'url' => env('APP_URL', 'http://yourappdefault.app'), ``` If you are referring to the environment setting as shown above, then you should ensure that you have updated your `.env` file to set the APP\_URL value as appropriate. Otherwise the default value (`http://yourappdefault.app`) will be used in your Postman collection. Example environment value: ``` APP_URL=http://yourapp.app ``` Modify the generated documentation ---------------------------------- [](#modify-the-generated-documentation) If you want to modify the content of your generated documentation, go ahead and edit the generated `index.md` file. The default location of this file is: `public/docs/source/index.md`. After editing the markdown file, use the `api:update` command to rebuild your documentation as a static HTML file. ``` $ php artisan api:update ``` As an optional parameter, you can use `--location` to tell the update command where your documentation can be found. Skip single routes ------------------ [](#skip-single-routes) If you want to skip a single route from a list of routes that match a given prefix, you can use the `@hideFromAPIDocumentation` tag on the Controller method you do not want to document. ### License [](#license) The Lumen API Documentation Generator is free software licensed under the MIT license. ### Health Score 34 — LowBetter than 77% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity27 Limited adoption so far Community24 Small or concentrated contributor base Maturity57 Maturing project, gaining track record Bus Factor1 Top contributor holds 67.1% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 2815d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/58f0b7a6b4a01c486263394e1414b3296ded35a5b565213a77aa906410137beb?d=identicon)[davmixcool](/maintainers/davmixcool) --- Top Contributors [![mpociot](https://avatars.githubusercontent.com/u/804684?v=4)](https://github.com/mpociot "mpociot (173 commits)")[![lucasmichot](https://avatars.githubusercontent.com/u/513603?v=4)](https://github.com/lucasmichot "lucasmichot (21 commits)")[![davmixcool](https://avatars.githubusercontent.com/u/5640065?v=4)](https://github.com/davmixcool "davmixcool (16 commits)")[![oxycoder](https://avatars.githubusercontent.com/u/5463953?v=4)](https://github.com/oxycoder "oxycoder (14 commits)")[![grinry](https://avatars.githubusercontent.com/u/5575688?v=4)](https://github.com/grinry "grinry (5 commits)")[![fergthh](https://avatars.githubusercontent.com/u/9524225?v=4)](https://github.com/fergthh "fergthh (4 commits)")[![idirouhab](https://avatars.githubusercontent.com/u/1987319?v=4)](https://github.com/idirouhab "idirouhab (2 commits)")[![MarkVaughn](https://avatars.githubusercontent.com/u/39970?v=4)](https://github.com/MarkVaughn "MarkVaughn (2 commits)")[![rudiedirkx](https://avatars.githubusercontent.com/u/168024?v=4)](https://github.com/rudiedirkx "rudiedirkx (2 commits)")[![antimech](https://avatars.githubusercontent.com/u/13885653?v=4)](https://github.com/antimech "antimech (2 commits)")[![nerijunior](https://avatars.githubusercontent.com/u/17169?v=4)](https://github.com/nerijunior "nerijunior (1 commits)")[![rick-hidef](https://avatars.githubusercontent.com/u/3083488?v=4)](https://github.com/rick-hidef "rick-hidef (1 commits)")[![sergiobelya](https://avatars.githubusercontent.com/u/6141086?v=4)](https://github.com/sergiobelya "sergiobelya (1 commits)")[![spirant](https://avatars.githubusercontent.com/u/2412672?v=4)](https://github.com/spirant "spirant (1 commits)")[![travoltron](https://avatars.githubusercontent.com/u/2647090?v=4)](https://github.com/travoltron "travoltron (1 commits)")[![tvbeek](https://avatars.githubusercontent.com/u/2026498?v=4)](https://github.com/tvbeek "tvbeek (1 commits)")[![yespbs](https://avatars.githubusercontent.com/u/478293?v=4)](https://github.com/yespbs "yespbs (1 commits)")[![zakhttp](https://avatars.githubusercontent.com/u/16402019?v=4)](https://github.com/zakhttp "zakhttp (1 commits)")[![atorscho](https://avatars.githubusercontent.com/u/7644596?v=4)](https://github.com/atorscho "atorscho (1 commits)")[![bosz](https://avatars.githubusercontent.com/u/6331902?v=4)](https://github.com/bosz "bosz (1 commits)") --- Tags apilaraveldocumentationlumen ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/davmixcool-lumen-apidoc-generator/health.svg) ``` [![Health](https://phpackages.com/badges/davmixcool-lumen-apidoc-generator/health.svg)](https://phpackages.com/packages/davmixcool-lumen-apidoc-generator) ``` ### Alternatives [knuckleswtf/scribe Generate API documentation for humans from your Laravel codebase.✍ 2.3k12.2M45](/packages/knuckleswtf-scribe)[darkaonline/l5-swagger OpenApi or Swagger integration to Laravel 2.9k34.0M112](/packages/darkaonline-l5-swagger)[mpociot/laravel-apidoc-generator Generate beautiful API documentation from your Laravel application 3.5k3.1M12](/packages/mpociot-laravel-apidoc-generator) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)