Laravel-apidoc-generator: Preparing for the next major release

[shalvah]

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

[shalvah]

Sneak peek of the new documentation.😄

[BenjaminRosell]

Awesome !
I think adding full Laravel Vapor support would be great :)
The ability to document authentication will be absolutely awesome! In my opinion we need a better way to document generic information that might not be related to a specific endpoint.

You guys are going a great job. Keep it up :)

[shalvah]

We'll be switching from Documentarian to https://github.com/knuckleswtf/pastel. I forked it from Documentarian and removed the bits that we had to work around, as well as made things simpler and touched up the template visually a bit.

I think adding full Laravel Vapor support would be great :)

I can't commit to this, as this is not a small task. Someone who uses Vapor could PR that.

In my opinion we need a better way to document generic information that might not be related to a specific endpoint.

Yes, we aim to make this better.

[BenjaminRosell]

Great !

I dont think we are very far from Vapor compatibility. I was able to fix a few issues with an artisan command. I will try to contribute :)

[ggolda]

Thanks for this awesome tool. My list of suggestions:

1. It would be great to have an option to customize documentation templates. Current theme is a little bit ugly (no offense, you did a great job!). Take a look at stripe API docs for example: https://stripe.com/docs/api. This package already supports almost all functions that are required, but design is outdated.
2. Ability to exclude a route from code instead of config file would be great.
3. Ability to add custom markdown templates while documenting in routes. E.g. @markdown template.test.md

[shalvah]

It would be great to have an option to customize documentation templates. Current theme is a little bit ugly (no offense, you did a great job!)

Have you checked out what the newer documentation will look like? http://knuckleswtf.github.io/pastel. It's not the prettiest, but it's a slight improvement. The ability to customise templates will come someday (needs to be in Pastel), but it's not anytime soon, as it's not a key focus.

[shalvah]

Ability to add custom markdown templates while documenting in routes. E.g. @markdown template.test.md

Hmmm... What's the utility of this? You can already write a Markdown description in the doc comment.

[ggolda]

Ability to add custom markdown templates while documenting in routes. E.g. @markdown template.test.md

Hmmm... What's the utility of this? You can already write a Markdown description in the doc comment.

Yep, but sometimes you need to add a large explanation about how this method work. If it is done in phpdoc comments, controller file become too large.

It would be great to have an option to customize documentation templates. Current theme is a little bit ugly (no offense, you did a great job!)

Have you checked out what the newer documentation will look like? http://knuckleswtf.github.io/pastel. It's not the prettiest, but it's a slight improvement. The ability to customise templates will come someday (needs to be in Pastel), but it's not anytime soon, as it's not a key focus.

Yes, I checked that one. It's slightly better but far from ideal :)

[shalvah]

Ability to exclude a route from code instead of config file would be great.

@ggolda this is possible by the way, using @hideFromAPIDocumentation

[K2ouMais]

Could you insert a way to document file uploads?

I have an endpoint to upload a file, but I cant get it to do a clear documentation.

Even the query examples dont have this. This means I have to change all query examples (in index.md) manually in the languages (bash, php, javascript) I want.

Changes in the index.md leads to skipping those when in need to generate the documentation again. And that is also a pain.

That would be a big help.

Thank you for the work you are doing.

[shalvah]

How do you suggest we handle the file upload in the example requests?

[K2ouMais]

This is the example I have right now:

@bodyParam file file required Your authorisation file. Example: C:\myFile.pdf

I am clearly saying the type of the field.

The bash Example request is this:

curl -X POST \
    "http://lei-api-frontend.test/api/authorisationfiles/upload" \
    -H "Content-Type: application/vnd.api+json" \
    -H "Accept: application/vnd.api+json" \
    -H "Authorization: Bearer {token}" \
    -d '{"file":"C:\\myFile.pdf"}'

The example request is wrong. (Not only bash, but also PHP Guzzle and Javascript)

It should be like this:

curl -X POST \
    "http://lei-api-frontend.test/api/authorisationfiles/upload" \
    -H "Content-Type: application/vnd.api+json" \
    -H "Accept: application/vnd.api+json" \
    -H "Authorization: Bearer {token}" \
    -F "file=@/C:/myFile.pdf"

Another thing that I just saw is that I cant import the generated Postman Collection into Postman.

I get an error doing that. Will have to take a look further.

Thank you

[Equruler]

Can't wait for @responseParam~

[shalvah]

It's coming!😄

[shalvah]

Another thing that I just saw is that I cant import the generated Postman Collection into Postman.

@K2ouMais this must have been a specific case. Please do look into it further.

[ScopeyNZ]

I have a branch with @responseParam work if you want to have a look @shalvah, I originally started it for 4.x:

https://github.com/ScopeyNZ/laravel-apidoc-generator/tree/feature/response-parameters

I last worked on it a few weeks ago, but my team wants to come back and get it ready for prod over the next two weeks. And possibly look into adding @responseParam collection from transformers too.

[ScopeyNZ]

Is master or v5 the working branch for the new major?

[shalvah]

Here's how things stand:

A new version is coming out, which is a different package/repo. I'll make it public soon (in the next few days, hopefully). It still needs some work before release (mostly documentation and a few improvements), but I want to get it to a state where it's easier for people to contribute.

Why a new package? Mostly because it would be easier to maintain something that I have full control over. Migration will be a bit of a pain, but there'll be a migration guide that lists everything you need to know. And, unless you've written a lot of custom strategies or modified the templates, you probably won't be too bothered.

A lot of goodies coming in the new version, guys. Here's a sneak peek😀

[shalvah]

Right now, it's mostly documentation, a few enhancements and maybe some tests left. With a lot of work, we should have an alpha release in 2 weeks or less.

[K2ouMais]

I think this will be a cool new release. Thank you can't wait for it.

[ScopeyNZ]

Sounds great. I'd say we're "power users" of this package, and we're kind of stretching the limits of this right now.

unless you've written a lot of custom strategies or modified the templates

This is something we've done a lot of 😅. We've actually ditched documentarian for actual Slate as we were coming across missing features/incompatibilities.

Anyway, excited to see the new repo, and happy to help contribute more.

[shalvah]

New package is up! https://github.com/knuckleswtf/scribe. Docs are still getting updated, but there's a migration guide, getting started guide and overview of changes at https://scribe.readthedocs.io/. Also, check out the new sample at https://shalvah.me/TheCensorshipAPI/.

There's also a todo.md with a list of tasks that still need to be completed. I'm starting with the documentation tasks, so anyone who wants to can work on any of the others.

[K2ouMais]

Thank you @shalvah for the work done.

I already opened an issue on the new package.

When trying to generate the docs I am getting a lot of skipped routes with an ErrorException.

Maybe I am missing something.

[shalvah]

Here's the documentation on the new FormRequest support, for interested folks🙂.

[shalvah]

Scribe is now in beta.😄

The beta will last for a week or two, and then we'll go v1.

[K2ouMais]

@shalvah I tested the file import documentation and it was looking really good. I am looking forward for the 1.0 release. I just dont have the time for the project I was making right now.

EDIT:
I have to say that you docs are pretty good already. I will try a lot of that stuff incl. ApiResources and so on...

[shalvah]

Scribe is out of beta! This project will be abandoned in favour of Scribe, so time to get migrating.😄