Anybody using auto-generated API documentation?

I'm not familiar with swagger, but there are a number of tools which can help with this. Personally I use doxygen due to my need for multi-language support, but there are other options like phpdox and phpDocumentor geared specifically towards PHP development.

In most cases these tools require PHPdoc style comments of one form or another, but these seem to be pretty much standard these days and Laravel already uses them.

As to which tool is best, largely that's a matter of personal choice and taste. I tend to favour those which can be extended, customised and whose output can be styled easily.

Thanks for the input, qgates.

While I do plan on using something like doxygen or phpDocumentor for generating documentation for my source code, they don't seem like the best solutions for generating API references that will be used by both internal and external developers.

I spent a good deal of time researching this yesterday and I'm becoming more convinced that it's better to invest the time in writing a good API spec and coding to that rather than trying to auto-generate an API reference from your code (or from PHP doc blocks). Right now I'm looking at Snow Crash (https://github.com/apiaryio/snowcrash) and Slate (https://github.com/tripit/slate) as ways of quickly putting together an API spec. I'm currently leaning more toward Snow Crash because you can use it with Dredd (https://github.com/apiaryio/dredd) to automate verifying that your endpoints match the spec.

The big advantages I see to this method are:

• You have more control over the structure and format of your documentation
• By designing the spec first, you can plan a better API and implement it using TDD
• Separating the spec from your code discourages casual modifications to the spec
• Testing endpoints based on the spec helps catch non-backwards-compatible changes
• It's language agnostic, so the same system can be reused for our NodeJS / Ruby APIs

As it stands, this seems like the superior solution for my development team, but I would love to be convinced otherwise if anybody has gone down this route before. :)

We use swagger. We do not use the auto generated code, we just manually build the son files that it needs. We actually store the documentation as php arrays, and have a route that returns the JSON format of the arrays to allow us to keep some comments in the php code to remark what is what.

swagger's documents are very confusing, so we just studied the JSON on the example sites, and then cross referenced our assumptions with the documentation.

@jimmy.puckett that's an interesting solution. I'm curious if you have any problems with your documentation getting out of sync with your implementation?

Yes, but we feel no more so than not updating the docblock for the generator to parse.

Our team uses API Blueprint for our internal API's. It works really well for our workflow. It may be a little bit too much upkeep for you, but if you want something that is very flexible, easy-to-write, and has a huge environment of plugins surrounding it, I would very much recommend you take a look.

Our team was using a custom PHPDoc parser for our api, and it became way too unwieldy in the code. The biggest problem, though, was actually that there was no easy way to show what the responses looked like with that style of generator. It isn't really feasible to have that in a php doc. So we explored all of the options, and I feel like API Blueprint won hands down.

Some reasons we really like it:

• The documentation it generates is really good looking and responsive
• Very easy to write (just uses markdown)
• Tons of plugins
  • Specifically Aglio and api-mock
• It lives in the repository and get's versioned with the code

We actually wrapped aglio with an artisan command and run that as part of our deployment process. Works wonders!

Hope this helps.

@cconey, thanks for the input!

I've been experimenting with API Blueprint, both building locally with something like Aglio and building in the cloud with the web service Apiary (by the people who maintain API Blueprint). I really like it for all the same reasons you mentioned and also because you can use it with Dredd to run very simple automated tests against your endpoint to verify everything stays in sync.

Unfortunately, I feel like it's also lacking a lot of features that are really important for this kind of solution. For example, you can only describe required URI parameters, if you want to describe required content for a JSON request you have to write cumbersome JSON schema and the documentation generators don't create a reference table from the JSON schema in the API docs.

This seems like the best solution I've seen so far but it definitely has it's advantages and disadvantages. It seems the Apiary team is hard at work implementing new features so maybe I should just dive in with API Blueprint and keep an eye out for updates going forward.

Are there any good tutorials for getting swagger set up in laravel? Note, I have zero experience with Swagger. I'm building an API from scratch and would like to include Swagger as I'm building it, but I have no clue on how to get started.

Check out: https://github.com/f2m2/apidocs

Although this question is a year old now, I thought I might respond anyway.

I automated my Laravel 5.x project documentation some time ago using both Doxygen and PHPdocumenter driven from a shell script run via CRON.

Basically I use the config and a template file for each project and add some metrics to the main page, it requires me to add comments to everything but I do that as a matter of course as I write code. Having both allows me to capture errors and "TODO" items using PHP documentor2 and get nice formatted docs from Doxygen.

I have not implemented an API document generator yet but that's next on the list.

API Docs Generator https://hello-api.readme.io/docs/api-docs-generator

I just released a new package: Blueprint Docs - An API Blueprint Renderer for Laravel, themeable via Blade templates. No need to set up Aglio or similar when working with API Blueprint and Laravel. Any feedback is welcome! https://github.com/M165437/laravel-blueprint-docs