REST API documentation

[cebe]

I'd like to create a dedicated issue for this to keep track of information and links for this topic.

Things taken from #303:

• https://developers.helloreverb.com/swagger/
• http://zacstewart.com/2012/04/14/http-options-method.html
• http://www.restdoc.org/
• http://restdesc.org/
• WSDL (?)

More:

• https://twitter.com/zdne/status/442739968654725121

[lygfanye]

How about NelmioApiDocBundle(https://github.com/nelmio/NelmioApiDocBundle) ?

[cebe]

The idea looks nice, similar to what swagger-php does. will check it out.

[bryglen]

I will be excited what yii 2 will come up for api docs. Looking forward to it. 👍

[paunin]

IMHO: swagger is the best practice in RF API services

[fernandezekiel]

in my experience with swagger(that was like 5 months ago), the swagger UI does not support "resource" (out of the box) input classes and so you will have to annotate the body parameters individually to generate the input elements in the request form, i did modify the swagger UI itself and made it work,
this is my basis of doing that
https://api.groupdocs.com/v2.0/spec/

[paunin]

@fernandezekiel Yep! The same problem. Can you show your code?

[Faryshta]

I am surprised, i was trying to decide between swagger and NelmioApiDocBundle to create an api.

Doesn't NelmioApiDocBundle uses symfony components? is there a php conflict on that or makes it too slow?

[cebe]

There are a few things that are missing here:

• API Blueprint, https://apiblueprint.org/, https://github.com/apiaryio/mson
• RAML, http://raml.org/about/about-raml
• Not so much about docs but a bit related: http://jsonapi.org/

[ilyar]

Update for OpenAPI Specification (fka Swagger RESTful API Documentation Specification) http://swagger.io/specification/

• https://github.com/zircote/swagger-php Compatible with the Swagger 2.0 specification.
• https://github.com/fsbahman/apidoc-swagger Inline Documentation for RESTful web APIs base on https://github.com/apidoc/apidoc-core (http://apidocjs.com)

[cebe]

citing @nostop8 from #62 (comment):

Simple REST API on-fly generator: https://packagist.org/packages/nostop8/rest-api-doc
Takes all the generated rules from urlManager, grabs information about the endpoint using Reflection. Very primitive, yet a good overview of what you've built and provides ability to test it quickly without having to write any single line of code. Additionally you can provide description of the service, it's params, model(s) etc.

[ddanielroche]

@cebe I propose to review this extension https://packagist.org/packages/light/yii2-swagger

swagger-php intergation with yii2.
Integration swagger-ui with swagger-php.

See these demos
https://github.com/lichunqiang/yii2-swagger-demo
http://petstore.swagger.io

I'm trying it on a personal project
regards

[yii-bot]

Issue moved to yiisoft/yii-api#14