Generation of the API documentation

[nalysius]

The online documentation seems to be out of date and as a developer it is difficult to think about update the online documentation at the same time as developing an API method. An other problem with the online documentation is that it is required to have an Internet connection to view it, so when developing in a train or something it's not possible to see the documentation. The documentation is the subject of #2903
The ideal would be to be able to generate the documentation when we need it. Doing so, we will be able to generate our own documentation on our local machine during development, and it doesn't prevent an online documentation that may be updated more frequently and more easily.

To do so I've included the mpociot/laravel-apidoc-generator package that generates the API documentation using the routes and the doc blocks. So, a developer updating the API only has to update the doc block.

To generate the documentation you can execute the command
php artisan api:generate --routePrefix="api/v1/*"

[jbrooksuk]

Interesting!

I don't have a much time at the moment, but please leave this with me and I'll take a look when I can. Perhaps @joecohens could help out here?

[nalysius]

I'm glad to know you are interested!

I understand that you haven't lot of time, when you'll have a moment to touch that you can leave a comment here, I'm available if some modifications are needed.

For the documentation I've set doc blocks above the API methods by mixing the content of the online documentation an what I've found in the code. If there are some elements that are missing or wrong I'll update them.

[jbrooksuk]

I've just checked the branch out and it generated really nicely. I'd be keen on keeping documentation in sync with the hosted docs though. Is there something we could do to sync with https://readme-sync.readme.io/docs/full-example?

[nalysius]

It seems readme.io uses the ApiDoc standard. So I could update some things in the doc blocks in order to use ApiDoc instead. If so, the only thing to so would be generating the file ./doc/api_data.json on the hosted doc.
It is pretty easy to do, I can do that it you're ok with that.

[joecohens]

I think that Readme feature using apiDoc is kind of stale, but we could do it using swagger https://readme.readme.io/docs/swagger-1

[nalysius]

It may be a good idea, Swagger is a well known standard. I know the package DarkaOnLine/L5-Swagger that generates Swagger from php doc, but it's compatible with PHP >= 7.1, do you know an other package that is compatible with PHP >=5.6?

[jbrooksuk]

I don't sorry, are any of their older versions compatible?

Do we need to support older versions of PHP to generate documentation though?

[nalysius]

An older version of the package (4.0 I think) is compatible with our version of PHP. But as said in the associated issue, should we write all the Swagger, or may a part be generated using the Laravel's routes?

[jbrooksuk]

We could write Swagger but that means it'll be out of date in two places potentially.

[nalysius]

Yes that's the problem, we could write Swagger ourselves ignoring Laravel's routes, but the problem is we could be outdated in the swagger. It's the same.
We aren't the firsts to use Swagger with Laravel, there is probably someone who uses Laravel's routes with Swagger in order to keep being synced.

[jbrooksuk]

http://blog.cjwfuller.com/2015/05/30/swaggervel/ Does this help?

[nalysius]

@jbrooksuk as you can see in the "Controller Annotation" section, the path is in the doc block.

@SWG\Api(
    path="/animals",
    @SWG\Operation(
        method="GET",
	summary="Fetch animals"
    )
)

The /animals path is the URL. If in our Laravel's routes we update the route, the one configured above becomes wrong.
In an ideal world, the annotation in the php doc would look for the path in the Laravel's routes for the current controller/action/method.

[jbrooksuk]

Wow, lots of changes here, awesome!

[nalysius]

Yes I have not finishes yet! But it's in progress. I'll try to finish that this weekend.

[GrahamCampbell]

Thanks for the PR @anthonybocci. Is this PR complete now? Is there anything outstanding we need to look at?

Also, can I ask why autopresenter has been removed?

[nalysius]

@GrahamCampbell this pull is old now, but I just checked and some controllers are not annotated so it's not finished. I'd a bit forgotten this to be honest. I have to finish it.

For autopresenter, I don't know. I don't know what it is really. What is it doing?

[GrahamCampbell]

Autopresenter is heavily used in the views. All models are replaced with their presented versions in the environment for view rendering.

[nalysius]

Ok I understand what it is and why it's useful. I don't remember removing it. It's probably a mistake.

[jbrooksuk]

@anthonybocci are you happy if we close this and go down the manual route for now?

[nalysius]

@jbrooksuk Yes you can. I am overwhelmed these times so I didn't finish this issue.