Update documentation about Cachet API

[hugomcfonseca]

Hello.

I would like to know if it is possible to update Cachet documentation about its API (preferably, including already new routes added for Cachet v2.4). I am trying to improve existing Golang client to be compatible with your latest Cachet's version.

Thanks and congrats about your great job with this app.

[nalysius]

Hello,

I'll take a look if laravel-apidoc-generator does the job. I would be really great if documentation was updated automatically.

[nalysius]

This issues throws an other question: the API documentation could be updated or generated via command line, but what about the rest of the documentation? It could be really great to have a resources/docs directory that contains markdown files that explain all the install process and other. They could be updated easier.

[jbrooksuk]

We could use something like Swagger?

[hugomcfonseca]

Yes, it would be fine by me @jbrooksuk. And Swagger will help to keep documentation updated every time a new endpoint is added/changed/deleted, so it would be great.

[nalysius]

The package DarkaOnLine/L5-Swagger seems to be the job.
I'll update my pull request to add the SwaggerPHP annotations in addition to the documentation block I've ever added.

[jbrooksuk]

I'm keen on this being generated to support Readme.io

[nalysius]

If we use ApiDoc (as discussed in #2929) there would be no need of Swagger and we could be synced with Readme.io.

[jbrooksuk]

It looks like ApiDoc is actually unsupported though. Swagger may be the preferred option.

[nalysius]

It could be great if a package would be able to use the Laravel's routes and the doc block to generate Swagger. Swagger-php needs all the information, but perhaps an other package or a wrapper would be able to do more?

[jbrooksuk]

I don't know much about Swagger, but yeah it would be very cool!

[nalysius]

I'm not sure if there is a such package. It would be annoying to type path and method for every route. It could be almost sufficient to generate the swagger.

[nalysius]

I suggest to accept the documentation update that I'd done in #2929 because generated documentation always uses PHP Doc, and keeping this issue open.
When we find a package that uses Laravel's routes to generate a Swagger file we'll add it.
What do you think about it?

[jbrooksuk]

I think we should get Swagger working because that's what we need to update Readme.io with.

[nalysius]

I agree to get Swagger working. The thing with swagger-php is we have to write all path (/api/v1/components) on every method, it's not synced with the Laravel's routes.
Any solution to that point?

[jbrooksuk]

Nah, but if that's what it takes, maybe we just get on with it?

[nalysius]

If we have no solution for that, we could use Swagger with an effort to keep the documentation up to date. If you're ok with that, I'll add Swagger to my PR.

[jbrooksuk]

Let's go with Swagger. We can import it into Readme.io then.

[jbrooksuk]

Alternatively, we could export documentation into this https://readme.readme.io/docs/importing-documentation

[jbrooksuk]

I'm actually going to do that as well because it's super useful.

[jbrooksuk]

(Not for API).

[jbrooksuk]

Exported to https://github.com/CachetHQ/Docs which does contain the API pages, but with no actual API info in them.

[ghost]

This issue was moved by @jbrooksuk to cachethq/docs/issues/4.