Laravel API Documentation Generator

Related tags

laravel postman
Overview

Laravel API Documentation Generator

Automatically generate your API documentation from your existing Laravel/Lumen/Dingo routes.

php artisan apidoc:generate

Latest Stable VersionTotal Downloads License codecov.io Scrutinizer Code Quality Build Status StyleCI

Installation

PHP 7.2 and Laravel/Lumen 5.7 or higher are required.

If your application does not meet these requirements, you can check out the 3.x branch for older releases.

composer require --dev mpociot/laravel-apidoc-generator

Laravel

Publish the config file by running:

php artisan vendor:publish --provider="Mpociot\ApiDoc\ApiDocGeneratorServiceProvider" --tag=apidoc-config

This will create an apidoc.php file in your config folder.

Lumen

  • When using Lumen, you will need to run composer require mpociot/laravel-apidoc-generator instead.
  • Register the service provider in your bootstrap/app.php:
$app->register(\Mpociot\ApiDoc\ApiDocGeneratorServiceProvider::class);
  • Copy the config file from vendor/mpociot/laravel-apidoc-generator/config/apidoc.php to your project as config/apidoc.php. Then add to your bootstrap/app.php:
$app->configure('apidoc');

Documentation

Check out the documentation at the Beyond Code homepage.

License

The Laravel API Documentation Generator is free software licensed under the MIT license.

Issues
  • No response body (Null) in the docs

    No response body (Null) in the docs

    OK Here's what I investigated

    • PHP 7.1
    • "dingo/api": "1.0.*@dev",
    • "mpociot/laravel-apidoc-generator": "^2.0",
    • a fresh project with only few "users" REST routes with api.auth middleware
    • JWT token is VALID!

    when calling command like this

    php artisan api:generate --router="dingo" --routePrefix="v1" --actAsUserId=1 --header="Authorization : Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOjEsImlzcyI6Imh0dHA6Ly9pbXVzaWZ5LmxhcmEubG9jL2FwaS9hdXRoZW50aWNhdGUiLCJpYXQiOjE0OTczNzEzNDYsImV4cCI6MTQ5NzM3NDk0NiwibmJmIjoxNDk3MzcxMzQ2LCJqdGkiOiJKeWlITWhvODZLcHVOZE1kIn0.mTNK1HO8b39QOrRBWlKfP5xxhLA2s_7RGgNiO4vD1so" I got 'Null' on every response example in the docs...

    I went to /Mpociot/ApiDoc/Generators/DingoGenerator.php method processRoute line 24 and dumped the exception here like this

    try {
        $response = $this->getRouteResponse($route, $bindings, $headers);
    } catch (Exception $e) {
        dump($e);
    }
    

    And gues what?! I get Exception on EVERY call !!!

    Symfony\Component\HttpKernel\Exception\UnauthorizedHttpException {#2074
      -statusCode: 401
      -headers: array:1 [
        "WWW-Authenticate" => null
      ]
      #message: "Failed to authenticate because of bad credentials or an invalid authorization header."
    

    That's why there's no response example on any route at all

    If someone interested I attached stack_trace.txt here

    Please someone tell how to fix or bypass this

    opened by c00p3r 51
  • Dingo/API support

    Dingo/API support

    Thank for this great tool! I noticed that routes created by the Dingo/API package are not generating any documentation. Looks like this is not supported, so I would like to request for support of those routes to be documented as well :)

    opened by stelgenhof 50
  • Preparing for the next major release

    Preparing for the next major release

    Hello folks.

    It's been a while since our last major release, and I feel like the time has come to start thinking towards the next. Here are my thoughts so far:

    General goals

    This release is not primarily about breaking things or adding tons of new features. It's more about improving the developer experience. More on that later.

    There's also something for the maintainers (me). Another goal is to keep the project lightweight and easy to maintain. That may involve splitting it up, removing stuff, or changing things as needed. No one wants to go crazy because of code.

    Support update

    • At the very least we'll require Laravel 6 and above, and probably PHP 7.3 and above. Why? It will make maintenance of this package easier, since there'll be less versions to cater for. It will reduce how much juggling of dependencies we have to go through (^x.a|^y.b|^z.c) to keep it working on all versions. It might seem drastic making PHP 7.3/L6 the minimum, but the PHP world has changed. We're building a culture of moving forward and keeping our shit updated. PHP 7.2 is no longer in active support. and hopefully our move will help encourage more people to update.

    • I'm also considering dropping official support for Dingo router and Lumen. Why? Dingo API is nice, but it using a different router from Laravel complicates things a bit. I wonder if there is enough usage out there to justify it. The last issue relating somewhat to Dingo was opened nearly a year ago. The Dingo overhead is not that much, though, so if I can be assured it actually gets used, I could keep it. As for Lumen, it's a zombie framework that keeps making life hard for package developers. Its time is past, and I really see no good reason for people to use it, or for me to support it. Someone needs to convince me otherwise.

    Possible additions

    • First-class support for authenticaton on routes.
    • Allow specifying multiple response types with scenario descriptions. See https://github.com/mpociot/laravel-apidoc-generator/issues/718#issuecomment-606851862
    • The ability to describe fields in the response. The obvious way to do this would be an annotation like @responseParam, but is that the best way? I'm open to suggestions.
    • Support for closures. (#690) This isn't a priority, but we'll consider it.
    • Allow indication of binary responses. (#479)
    • Support for factory states. (#686, #452)
    • Support for apiResources with relations/pagination + more. (#641, #642, #663)

    Improving the experience

    • Better documentation. Aiming for a clearer and friendlier guide, along with reference docs.
    • General DX improvements. No specific features in mind, but we're willing to rethink some of the core internals of this package if that would improve the DX. For a start, I've been thinking about how we can fully leverage all the info we can pull from the framework about the routes, before needing the dev to annotate anything.

    I may also fork mpociot/documentarian into a new repo. It's largely unmaintained, and holds us back whenever a new Laravel release comes out. It also has some kinks that I had to create workarounds for, so it would be nice to get rid of those. I don't know if I have the time or energy, though.

    Documentation is a solved yet unsolved problem. We want to help smoothen out the kinks in the process. I'd like to hear your thoughts. What are your biggest pain points about documenting your APIs (whether it involves this package or not)?

    opinion next 
    opened by shalvah 27
  • Expected a string. Got: boolean

    Expected a string. Got: boolean

    Hi there,

    Installed dev-master because 1.2 did not want to install

     Problem 1
        - Conclusion: don't install mpociot/laravel-apidoc-generator 1.2.3
        - Conclusion: don't install mpociot/laravel-apidoc-generator 1.2.2
        - Conclusion: don't install mpociot/laravel-apidoc-generator 1.2.1
        - Conclusion: remove phpdocumentor/reflection-docblock 3.0.2
        - Installation request for mpociot/laravel-apidoc-generator ^1.2 -> satisfiable by mpociot/laravel-apidoc-generator[1.2.0, 1.2.1, 1.2.2, 1.2.3].
        - Conclusion: don't install phpdocumentor/reflection-docblock 3.0.2
        - mpociot/laravel-apidoc-generator 1.2.0 requires phpdocumentor/reflection-docblock ~2.0 -> satisfiable by phpdocumentor/reflection-docblock[2.0.0, 2.0.1, 2.0.2, 2.0.3, 2.0.4].
        - Can only install one of: phpdocumentor/reflection-docblock[2.0.0, 3.0.2].
        - Can only install one of: phpdocumentor/reflection-docblock[2.0.1, 3.0.2].
        - Can only install one of: phpdocumentor/reflection-docblock[2.0.2, 3.0.2].
        - Can only install one of: phpdocumentor/reflection-docblock[2.0.3, 3.0.2].
        - Can only install one of: phpdocumentor/reflection-docblock[2.0.4, 3.0.2].
        - Installation request for phpdocumentor/reflection-docblock (locked at 3.0.2) -> satisfiable by phpdocumentor/reflection-docblock[3.0.2].
    

    And now I get this:

      [InvalidArgumentException]       
      Expected a string. Got: boolean  
    
    opened by cerw 22
  • [3.0] Make package work with Lumen

    [3.0] Make package work with Lumen

    An implementation was attempted in #267, but wasn't approved. Since we're bumping v3 up to require 5.6 or above (and getting rid of the FormRequest dependency - see #343), now would be a good time to try again. cc @gazben

    hacktoberfest 3.0 
    opened by shalvah 21
  • Add another maintainer?

    Add another maintainer?

    There are 21 pull requests and now 71 issues in here. This is a great project, but it can get overwhelming for one person. Would you consider adding another maintainer that can handle some of the issues and merging of pull requests @mpociot ? I'd be more than happy to help.

    opened by watzon 21
  • Add support for Laravel Vapor

    Add support for Laravel Vapor

    Currently the package doesn't seem to be compatible with Laravel Vapor out of the box. I've added a temporary route to solve it for personal use but would be nice if a more robust implementation could be bundled into the package.

    Route::get('/docs', function () {
    	$contents = file_get_contents(asset('docs/index.html'));
    	$contents = str_replace(env('APP_URL') .'/', asset('/'), $contents);
    
    	$contents = str_replace('href="css', 'href="'. asset('/') .'docs/css', $contents);
    	$contents = str_replace('src="js', 'src="'. asset('/') .'docs/js', $contents);
    	$contents = str_replace('src="images', 'src="'. asset('/') .'docs/images', $contents);
    
    	return $contents;
    });
    

    Let me know if I can help further in this 👍🏻

    opened by devonmather 19
  • Lumen 5.8 - example response is null

    Lumen 5.8 - example response is null

    I made all according the documentation for Lumen. All is working on default settings. Generator sees routes, when I make: php artisan apidoc:generate I can see: Processed route: [GET] /api/test Wrote index.md to: public/docs Generating API HTML code Wrote HTML documentation to: public/docs/index.html Generating Postman collection

    But example response is null

    opened by adam-kozlo 18
  • @response does not show up

    @response does not show up

    /**
     * @response {
     *  data: [],
     *}
     */
    

    What I have to do to make it work ? 1.7.0

    opened by misiek303 16
  • !! THIS PACKAGE IS ABANDONED !! -

    !! THIS PACKAGE IS ABANDONED !! -

    I am not the owner.

    For a currently maintained package see: https://github.com/knuckleswtf/scribe

    opened by Sunhat 0
  • Set this repo as archived or remove it from github

    Set this repo as archived or remove it from github

    Please, archive or delete this project.

    opened by neoacevedo 1
  • fix: responseFile convert empty object to array

    fix: responseFile convert empty object to array

    responseFile convert empty object to array due to json_decode($content, true) Example

    {"foo":{}}
    

    convert to

    {"foo":[]}
    
    opened by deathkel 0
  • [Bug] Take output path from configuration when building

    [Bug] Take output path from configuration when building "apidoc::partials.info" partial

    The apidoc::partials.info partial contains the link to Postman generated documentation, but it always outputs the link at /docs/collection.json, no matter the actual output folder that's configured.

    This bugfix should output the link to Postman collection to whatever the output is configured at.

    opened by arukompas 0
  • Unabale to install

    Unabale to install

    Problem 1 - mpociot/laravel-apidoc-generator[3.15.1, ..., 3.x-dev] require illuminate/routing ^5.5|^6.0 -> found illuminate/routing[v5.5.0, ..., 5.8.x-dev, v6.0.0, ..., 6.x-dev] but these were not loaded, likely because it conflicts with another require. - mpociot/laravel-apidoc-generator[3.0.0, ..., 3.3.2] require illuminate/routing 5.5.* || 5.6.* || 5.7.* -> found illuminate/routing[v5.5.0, ..., 5.7.x-dev] but these were not loaded, likely because it conflicts with another require. - mpociot/laravel-apidoc-generator[3.4.0, ..., 3.15.0] require illuminate/routing 5.5.* || 5.6.* || 5.7.* || 5.8.* -> found illuminate/routing[v5.5.0, ..., 5.8.x-dev] but these were not loaded, likely because it conflicts with another require. - Root composer.json requires mpociot/laravel-apidoc-generator 3.x -> satisfiable by mpociot/laravel-apidoc-generator[3.0.0, ..., 3.x-dev].

    I am unable to install it on laravel 8

    opened by abbasmashaddy72 6
  • When installing the package, an error is reported.

    When installing the package, an error is reported.

    laravel/framework v8.50.0 PHP7.3.9

    composer require mpociot/laravel-apidoc-generator

    Using version ^4.8 for mpociot/laravel-apidoc-generator ./composer.json has been updated Running composer update mpociot/laravel-apidoc-generator Loading composer repositories with package information Updating dependencies Your requirements could not be resolved to an installable set of packages.

    Problem 1 - mpociot/laravel-apidoc-generator[4.8.0, ..., 4.8.2] require illuminate/console ^5.7|^6.0|^7.0 -> found illuminate/console[v5.7.0, ..., 5.8.x-dev, v6.0.0, ..., 6.x-dev, v7.0.0, ..., 7.x-dev] but these were not loaded, likely because it conflicts with another require. - mpociot/laravel-apidoc-generator v4.x-dev requires ramsey/uuid ^3.8 -> found ramsey/uuid[3.8.0, ..., 3.x-dev] but the package is fixed to 4.1.1 (lock file version) by a partial update and that version does not match. Make sure you list it as an argument for the update command. - Root composer.json requires mpociot/laravel-apidoc-generator ^4.8 -> satisfiable by mpociot/laravel-apidoc-generator[4.8.0, 4.8.1, 4.8.2, v4.x-dev].

    Use the option --with-all-dependencies (-W) to allow upgrades, downgrades and removals for packages currently locked to specific versions.

    Installation failed, reverting ./composer.json and ./composer.lock to their original content.

    opened by andyzu 13
  • Error on Generating API HTML code

    Error on Generating API HTML code

    Generating API HTML code

    ErrorException

    copy(resources/docs/js/all.js): failed to open stream: No such file or directory

    at vendor/mpociot/laravel-apidoc-generator/src/Writing/Writer.php:266

        262|             mkdir($publicPath, 0777, true);
        263|             mkdir("{$publicPath}/css");
        264|             mkdir("{$publicPath}/js");
        265|         }
    ->  266|         copy("{$this->sourceOutputPath}/js/all.js", "{$publicPath}/js/all.js");
        267|         rcopy("{$this->sourceOutputPath}/images", "{$publicPath}/images");
        268|         rcopy("{$this->sourceOutputPath}/css", "{$publicPath}/css");
        269| 
        270|         if ($logo = $this->config->get('logo')) {
    
          +17 vendor frames 
    

    18 artisan:37

      Illuminate\Foundation\Console\Kernel::handle(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
    
    opened by AlexGh12 0
  • Dev/change mpociot documentarian version requirement

    Dev/change mpociot documentarian version requirement

    Updating mpociot/documentarian requirement for Laravel 8.0 upgrade. Please kindly review. Cheers.

    opened by fredmeng 2
  • Headers from tags

    Headers from tags

    Adds support for @header tags

    opened by whizzrd 0
  • Faker dependencies

    Faker dependencies

    Hi, Would be need to update the composer.json?

    https://laracasts.com/discuss/channels/general-discussion/package-fzaninottofaker-is-abandoned-you-should-avoid-using-it-no-replacement-was-suggested

    Regards,

    opened by JJDSNT 1
Releases(4.8.2)
Creates an 'artisan workflow:make' command to scaffold out a number of useful GitHub actions workflows for Laravel

Laravel workflow generator This creates a make:workflow artisan command to scaffold out a number of useful GitHub actions workflows for Laravel. Insta

Len Woodward 9 Jul 18, 2021
A code generator for EasySwoole

wise-generator-easyswoole 基于EasySwoole的code-generation改写,主要应用与内部系统。基本上所有类都有所调整,同时也完善了一些功能。 版本说明 版本说明 code-generation 使用命令行,一键生成业务通用代码,支持代码如下: 一键生成项目初始

Ryan 3 Jun 8, 2021
Module Generator Composer Package For Laravel

Module Generator Installation You can install the package via composer: composer require teacoders/module-generator Run the command below to publish t

Tea Coders 20 Sep 6, 2021
Generate migrations from existing database structures

Laravel Migration Generator Generate migrations from existing database structures, an alternative to the schema dump provided by Laravel. A primary us

Bennett Treptow 240 Oct 22, 2021
Laravel IDE Helper

Laravel IDE Helper Generator Complete PHPDocs, directly from the source This package generates helper files that enable your IDE to provide accurate a

Barry vd. Heuvel 11.8k Oct 21, 2021
A PHP webpage that uses string replacements to generate a binary on the fly that you can enter at setup in NEOS.

openpilot-installer-generator A PHP webpage that uses string replacements to generate a binary on the fly that you can enter at setup in NEOS. What is

null 14 Sep 25, 2021
A PHP README File Generator, to generate easily your GitHub README files 🎉

Readme Generator ?? Requiremennts ?? Make sure you have PHP 8.0 or higher installed. Steup ⚙️ Install Composer v2 or higher (https://getcomposer.org)

♚ PH⑦ de Soria™♛ 2 Oct 24, 2021
Trial account generator for NoPing

NoPing account generator (beta version) Trial account generator for NoPing TODO It is working add some errors checks Add a good readme Host the server

Benjamin 6 Sep 14, 2021
:rocket: A Smart CRUD Generator For Laravel

Features Generate your models, views, controllers, routes and migrations just in a few clicks. Models visualization through a graph presentation (New

Houssain Amrani 860 Oct 21, 2021
⚙️ A Laravel package to decompose your installed packages, their dependencies, your app & server environment

Introduction Laravel Decomposer decomposes and lists all the installed packages and their dependencies along with the Laravel & the Server environment

LUBUS 501 Oct 12, 2021
🍪 Write gorgeous documentation for your products using Markdown inside your Laravel app.

LaRecipe Write gorgeous documentations for your products using Markdown inside your Laravel app. LaRecipe ?? LaRecipe is simply a code-driven package

Saleem Hadad 1.9k Oct 17, 2021
A cli tool for creating Laravel packages

Laravel Packager This package provides you with a simple tool to set up a new package and it will let you focus on the development of the package inst

JeroenG 1.1k Oct 18, 2021
This package extends the core file generators that are included with Laravel 5

Extended Migration Generators for Laravel 6, 7 and 8 Easily define the migration schema right in your make:migration command. The new commands this pa

Laracasts 2.4k Oct 18, 2021
⛔️ Laravel Tinx is archived and no longer maintained.

⛔️ Laravel Tinx (Deprecated) Laravel Tinx was archived on 12th December 2019 and is no longer maintained. Looking for a reloadable version of Laravel

James Furey 432 Oct 15, 2021
[Package] Lumen Testing Helper for Packages Development

anik/testbench-lumen is a package, highly inspired by the orchestral/testbench. orchestral/testbench that is a tool for testing Laravel packages.

Syed Sirajul Islam Anik 5 May 9, 2021
A MySQL Workbench plugin which exports a Model to Laravel 5 Migrations

MySQL Workbench Export Laravel 5 Migrations Plugin A MySQL Workbench plugin that allows for exporting a model to Laravel 5 migrations that follow PSR-

Brandon Eckenrode 889 Oct 16, 2021
Prequel for Laravel. Clear and concise database management.

TL;DR? Test Prequel here! What is Prequel exactly? Prequel is meant to be a database management tool for Laravel to replace the need for separate stan

Protoqol 1.3k Oct 17, 2021
A PHP-based sandboxing library with a full suite of configuration and validation options.

A full-scale PHP 5.4+ sandbox class that utilizes PHP-Parser to prevent sandboxed code from running unsafe code. It also utilizes FunctionParser to di

Corveda 165 Oct 15, 2021
A handful of tools for PHP developers.

Belt A handful of tools for PHP developers. Version 2.0.0 is out now. Clear documentation, improved tests and code quality. Installation In case you w

Ilya 738 Sep 4, 2021