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

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 :)

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)?

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  

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

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.

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 👍🏻

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

apidoc:generate failing after updating to latest release:

/vendor/mpociot/laravel-apidoc-generator/src/Commands/GenerateDocumentation.php:88
    84|         $parsedRoutes = $this->processRoutes($generator, $routes);
    85|         $parsedRoutes = collect($parsedRoutes)->groupBy('groupName')
    86|             ->sortBy(static function ($group) {
    87|                 /* @var $group Collection */
  > 88|                 return $group->first()['groupName'];
    89|             }, SORT_NATURAL);
    90|
    91|         $this->writeMarkdown($parsedRoutes);
    92|     }

being able to parse Form Requests and generate parameter listing was a nice feature, as it hooked into a framework feature, and it allowed devs to declare request parameters only once. But we keep running into more and more issues with this, such as #247, #162, #294, #285, #253, and more. In addition, this parsing process involves a lot of code gymnastics and is pretty non-deterministic. (see #333 - it fails unless rules are ordered in a certain way). I don't think it's worth it trying to maintain this, especially as Laravel's validation system keeps getting more and more robust.

And from an SRP perspective, it's arguable whether we should be using FromRequests to generate doc. When I come to the "description" field for a parameter, what I really want to see is the business rule description (for example, "this is the ID of the latest transaction to fetch", rather than "This must be numeric"). Achieving the former with FormRequests is difficult, and rightfully so. FormRequests are for validation, not information or user guides.

In line with this, version 3 will no longer parse form requests. We'll add a new annotation (@bodyParam ) that will replace this. Something like this:

/**
 * @bodyParam user_id string required The ID of the user
 * @bodyParam room string required The ID of the room to ban the user from
 * @bodyParam length int The length of the ban, in days. Defaults to 7.
 */
public function banUser() 
{
  // ...
}

Admittedly, it's limited (can't nest array/object params).. We'll see if we can improve on that. We're also open to alternate means that will make life easier for developers.

Outof box this is how it looks like for laravel 5.3: http://i.imgur.com/EgPohXf.png Styles missing.

I have executed following commands:

1. php artisan api:generate --routePrefix="api/v1/*" to generate docs
2. php artisan serve to serve content

I want to put the documents somewhere outside the controller. For example, in swagger you can put documents in an interface and implement it. Does scribe have that capability?

This is an automated pull request from Shift to update your package code and dependencies to be compatible with Laravel 9.x.

Before merging, you need to:

• Checkout the l9-compatibility branch
• Review all comments for additional changes
• Thoroughly test your package

If you do find an issue, please report it by commenting on this PR to help improve future automation.

install package not complete install because this error Your requirements could not be resolved to an installable set of packages. Problem 1 - 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.2.3 (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. - 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. - 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 versio

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.