Laravel-apidoc-generator: How can we improve your experience?

[shalvah]

How can we improve the experience you have as a developer using this package? How can we make it easier for you to generate reliable documentation and keep it up-to-date? Please share your thoughts in this thread.

[shalvah]

A few things I personally want to do to improve things:

• move documentation to https://readthedocs.org. At this point, we've outgrown the README. Moving the docs will also allow for better, more comprehensive documentation and examples.
• have a personal project or two solely for the purpose of testing this. I am no longer an active user of this package (haven't done Laravel in a while), so I've been a bit lacking in context when issues are brought up. Doing this will allow me observe the developer experience firsthand. It will involve a non-trivial time investment, though.

[helori]

Hi ! Unless I missed something, is there a way to generate example responses using Laravel built-in "Resources" instead of Transformers ? I guess Resources didn't exist at the time the package was written... Great work though !

[shalvah]

Hi ! Unless I missed something, is there a way to generate example responses using Laravel built-in "Resources" instead of Transformers ? I guess Resources didn't exist at the time the package was written... Great work though !

No, we don't support resources yet, though that feature has been requested. #375
I'll put it o0n the roadmap.

[tomChabo]

Hi! We just started to use the package and it's really helpful. I would like to know if there is a way to keep the modifications I do in the markdown file index.md. We don't need any bash language tab so I remove it. After pushing my new index.md file to the git repository, my colleague use the generate command and it removes my modifcation from index.md. Is there something we are doing wrong or updating the markdown is a possible future improvement?

[shalvah]

@tomChabo if you'd like to persist your changes you should use the rebuild command. See https://laravel-apidoc-generator.readthedocs.io/en/latest/generating-documentation.html#manually-modifying-the-content-of-the-generated-documentation.

But you'll be pleased to know you can now specify what languages you'd like to include in your config. https://laravel-apidoc-generator.readthedocs.io/en/latest/config.html

[charliegilmanuk]

Perhaps support other doc outputs, e.g. Vuepress, Swagger.

I've got a fully working fork with automated output to Vuepress format if you're interested: https://github.com/charliegilmanuk/laravel-apidoc-generator

The below preview was entirely generated from this:

[shalvah]

This looks good. We could consider it for version 4 (coming soon).

[MichalSeidler]

Please enable change default "mode":"formdata" in postman collection generator to other types. E.g. i use JSON instead of formdata.

[ncatanchin]

Running into problems everywhere.

• response_calls.body parameters are not being used
• postman collection defaults to http://
• body parameters are failing validation in laravel FormRequest
  ~* recent releases are buggy / not backwards compatible / no upgrade path~
• R3.11 has the bugs further above

~The package is no longer usable for us, at this stage, quite unfortunate.~

---

Edit to strike out misguided comments - the major issues I was experiencing were due to local problem in my application, an outdated override class I was not aware of.

[shalvah]

Hi @ncatanchin Sorry to hear that. Unfortunately, that's how things are with software sometimes—you break some stuff while moving forward. What I've got to say:

• Support for FormRequest rules was discontinued since v3, so I don't know why you list it now. However, we're moving to a plugin architecture in v4, which will allow anyone to create a plugin that uses FormRequest rules if they want to. PR: https://github.com/mpociot/laravel-apidoc-generator/pull/570
• Regarding the bugs you mention, I'm not aware of them, and the tests seem to cover those scenarios and have not encountered those bugs. No one else, including myself, has encountered the bug you complain about in #561. I did fix one or two bugs while working on the plugin feature, though. If you're still willing to give it a try, you can take out the dev-plugin-arch tag for a spin.
• Postman URLs defaulting to http is a minor annoyance, I'm sure. It's something I've not looked at because it's extremely low on _my_ list of priorities. I'll get to it when I have the time (and the interest). If it's a dealbreaker for you, there's no reason you can't send in a PR to fix this.

Cheers.

[shalvah]

Closing this in favour of #571

[ncatanchin]

Hi @shalvah, thanks for your response. As it turns out, the major problems were due to issues in my application, so I'm sorry for my hasty comment made out of frustration.

I have submitted a PR for the Postman issue, and hope to be able to contribute further to this package.

Thank you for your hard work here.

Regards

[shalvah]

FormRequest support is back in Scribe.😅