Generate API documentation

[NiCr42]

Is there any way of generating an end user API like swagger.io (or any other api documentation generator) ?

Thanks.

[lindyhopchris]

Hi! No not at the moment. It's not something I think I'd have time to get to based on everything else that needs to be done. I'd be interested in hearing your thoughts as to how it could be done if you had ideas?

[moneal]

You can use https://github.com/DarkaOnLine/L5-Swagger to generate documentation but it requires manually writing docblock comments for each method. I use Google Endpoints as a frontend for my API and it requires a swagger config to define requests. Its a bit of extra work but is nice. I would love for this to be autogenerated.

[chriscalip]

+1

[chriscalip]

How about a transition way of providing a swagger.json for https://github.com/cloudcreativity/demo-laravel-json-api

Comment withdrawn because swagger and jsonapi seems to be a pita to integrate.

Reference:
swagger-api/swagger-core#1849
Swagger customization for JSON API specification
Consensus: Swagger currently does not handle JSON API.

[igorsantos07]

This is sad. An API without documentation is like a book in a foreign language: the author know what was written, but readers can't get to the message without jumping to the dictionary very often.

It's also sad to see Swagger is hard to integrate with JSON-API, as both are beautiful tools for the API-land.

Another suggestions to check would be API Blueprint.

Would be nice if, at least, there was something like an OPTIONS endpoint that would spit out the available verbs, fields and other options each resource would respond to...

[lindyhopchris]

@igorsantos07 I'd happily take PRs if this is something you're able to help with. Unfortunately I haven't had time to get to this yet.

[igorsantos07]

I would love to be able to help on this, as I'm really sad with the state of REST APIs on PHP (been a past contributor to Restler), but unfortunately the project I'm in is quite time sensitive and I probably wouldn't have time to bring something back here... Will probably just use a different package / simpler API, or write docs by hand :(

[lindyhopchris]

That's ok - I understand. It's exactly the same for me, and I can only get to adding things into this package when there's time between work.

[johannesschobel]

Maybe this project here ( https://github.com/saleem-hadad/larecipe ) may be a viable strategy? Althoug it does not allow for automated doc generation from docblocks, it uses markdown to create quite beautiful docs..

However, if using this package would be an option, i would vote for "not including" this package by default but rather provide assistance in "how to include" it (e.g., write documentation on how to integrate both packages)

[lksnmnn]

We've built a Laravel package which generates API docs in JSON, HMTL and Swagger by reading from the Adapter/Schema/Validator classes. It is currently closed source and only works with laravel-json-api v0.26

I may find the time to update and release it.

[lindyhopchris]

@lksnmnn that sounds great! definitely let me know if you decide to open source it and if i can help in any way.

[daedeloth]

We've built a Laravel package which generates API docs in JSON, HMTL and Swagger by reading from the Adapter/Schema/Validator classes. It is currently closed source and only works with laravel-json-api v0.26

I may find the time to update and release it.

I'm about to do the same thing so if you are willing to release something, I'd love to have a look :-)

[lindyhopchris]

Also, if you see the discussion on #411 - we'd love to add this capability for v2 of this package. So if anyone here is working on that kind of thing, it'd be great to work towards adding it to this package so that people get the capability out of the box!

[crabmusket]

Has any thought been put towards using an existing specification (e.g. in OpenAPI format) to generate Laravel code using this package? I've just been reading through Phil Sturgeon's books on API design and he advocates for doing a spec first using e.g. OpenAPI, from which you can generate a bunch of useful things - clients, documentation, tests, mock servers, etc. I guess if the first step is writing PHP then you get an OpenAPI document out of it at the end, that's not too different, but I thought I'd ask!

EDIT: more on the subject. https://apisyouwonthate.com/blog/api-design-first-vs-code-first

[johannesschobel]

i think Design First is a very (!) good approach and i really like it. Naturally, you get the documentation "out of the box" - which is very helpful when maintaining a project / api or trying to get yourself comfortable with the latter.

I really like OpenApi 3 (OA3) and i think it is a great step into the right direction. However, when it comes to "combining OA3 & Json:API" i found out, that there are some severe issues that are not that easy to tackle. I.e., you dont want to duplicate yourself over and over and over again - which was one of the problem i stumbled upon.. (i.e., defining the model, the output structure and then again (an annotated version) for the open api document, and so on..)

[lindyhopchris]

So I think it would be great if this package was able to output OpenAPI information. Although I completely agree with the design-first approach (and typically that's how I work, though not using OpenAPI) - I wouldn't want to generate Laravel code from OpenAPI... I think the priority needs to be able to output OpenAPI info from the Laravel code.

My reasoning for this is the whole direction of travel for this package is to make it a lot more familiar to Laravel approaches... this has been a bit of a journey as this package started as a framework-agnostic package, so I've had to go through the pain of trying to make it more Laravel-y will trying not to continually introduce too many breaking changes. (Hopefully the journey to 2.0 as laid out in #411 will see that journey completed.) Generating Laravel code from OpenAPI therefore seems like the wrong-way round... most developers will come to this package from a Laravel background, not necessarily an OpenAPI background, so makes more sense to start with the Laravel code and then hopefully we can add a feature to output OpenAPI info from it.

#411 needs to happen first though. My job circumstances are changing from 01 Jan, so that's going to open up more time for open source - i.e. this package.

[lindyhopchris]

Might be worth someone playing with this:
https://laravel-news.com/enlighten-laravel-apis

To see what it produces if using this package.

[lindyhopchris]

Closing as this is a duplicate of #489