REST API documentation generation out of routes

[everzet]

Analyze defined routes and generate REST API documentation out of it (maybe with view layer configuration involved - acceptable formats)

[lsmith77]

Check the http://getfrapi.com/ screencast for some inspiration.

[everzet]

I've seen it already. But i don't like many things in their realization. First of all, their REST is not RESTful :-D

[lsmith77]

"inspiration" and I wasn't talking about their rest but their doc (and test) generation :)

[odino]

I personally don't like it, but could we discuss the generation of the documentation in the WADL format?

http://www.w3.org/Submission/wadl/

[HelloGrayson]

I wonder if a better direction than generation would be to provide some view helpers that allowed for quick building of documentation controllers/views. This seems better than simply generating a structure and would be more extensible/maintainable. In other words I think generating API docs works great for FRAPI's use case (drop into an app) but question if we need this feature "as-is" or if it even makes sense.

[odino]

Are we talking about documentation for the clients?

Bare in mind, that is what REST tries to avoid :)

[lsmith77]

odino: sure. but there are things like the fact that even if you follow HATEAOS you need to inspect headers. also while you should know to expect different status codes, its still good to know what status codes are "more likely". its just nice for casual review of the API.

also another topic that should be ignored: some clients just like killing trees and its nice to not have to waste a lot of time filling this pages of paper :)

[odino]

agree, the only thing we should avoid is to heavily rely on generated documentation, otherwise we would replicate WSDL

thumbs down for tree-killers :)

[vladar]

As far as I know, true REST API docs are about defining media types and their relations, not URLs. E.g. http://kenai.com/projects/suncloudapis/pages/Home , http://amundsen.com/media-types/collection/

But for simple HTTP APIs, which will be the case for 80% of web projects this feature would be still useful.

[odino]

Yes vladar, URI templates are obviously evil. But if we need to develop a REST bundle we should follow those principles.

A URI template would fit well for an ApiBundle

[HelloGrayson]

Might be able to take concepts from http://swagger.wordnik.com/

[immutef]

👍 to Swagger. This looks awesome!

[HelloGrayson]

To create a similar experience we might be able to:

• Parse methods marked as @apidoc or something
• Get description of method and parameters from docblock on @apidoc marked methods
• Allow for inline-testing of calls on a per action basis.

All in all I think achieving screens like Swagger is pretty do-able and makes tons of sense for this Bundle.

[HelloGrayson]

Another option would be simply generating the JSON that Swagger consumes but that comes with some weight (Java)... Would rather see a "like" implementation.

[immutef]

Generating compatible JSON was my first thought. I'll dig a little bit deeper on the weekend, maybe there's some quick 'n dirty prototyping possible.

[HelloGrayson]

@pminnieur seems like we could just as easily provide the same basic functionality rather than integrating.

[immutef]

At least it could work like https://github.com/FriendsOfSymfony/FOSJsRoutingBundle - just adding some fancy HTML/CSS and expose your RESTful routes with some kind of API docs. Maybe we could use some Annotations to support more informations.

[immutef]

I'd like to start with this but I think it would be better to put the code into a dedicated bundle (e.g. FOSRestAPIExplorerBundle). Question is, shall we support the Swagger API only (so Swagger is used to visualize the information gathered and exposed in JSON) or shall we provide our own web interface, too?

[lsmith77]

a separate Bundle sounds like a good idea. if we only support swagger we might want to say so in the Bundle name. i dont know if we also want to support something else. depends on your motivation and the quality of swagger. one question about swagger: how does that work with internal API's that one doesnt want to expose to an external service?

[immutef]

I think you simply have to not make the URL returning the Swagger JSON public if you don't want it to be public ... :D Seriously, I'd like to use annotations and if you don't want a route to be public, you won't add the @Expose() annotation or add @Expose(false) -- something like this. Just like FOSJsRoutingBundle is configurable how to deal with it (expose everything by default, or expose whitelisting). If you mean "here's a link for our public API and this link is only for you", we may add an annotation like @Api("public") and @Api("private") including the security component so you could hand out different API documentations to different people (and control the access to 'em).

For the name: I'd like to have a generic name, Swagger would be the first API documentation service to be supported. If people want to add any other service, they could just do it (and must not start from scratch). @odino for example could add the WADL support. At least I'd like to provide a web interface, too.

[immutef]

I created a GitHub repository so far to collect ideas and issues before we get started. Feel free to open issues for any questions or topics to discuss (naming could be discussed too, for sure) ;-)

https://github.com/pminnieur/FOSRestApiExplorerBundle

[lsmith77]

ok good. once things have shaped up .. we can move it to FOS

[HelloGrayson]

Are you planning on taking advantage of https://github.com/wordnik/swagger-ui as the "displayer"?

[immutef]

in the first place, yes. only generate swagger-spec conform json to be used by the swagger-ui.

[lsmith77]

closing in favor of https://github.com/nelmio/NelmioApiDocBundle

[oliver-ideahq]

I know this is very old, but some things changed since then and I found this relatively quickly whilst looking for a package/bundle for Swagger / Openapi.
Any chance to reconsider this? Since the NelmioApiDocBundle is abandoned and I can't see any real alternative that integrates into Symfony for Swagger / OpenApi (or any other really, RAML, ...?).