REST API documentation - Githubissues

yiisoft / yii2

Yii 2: The Fast, Secure and Professional PHP Framework

http://www.yiiframework.com

BSD 3-Clause "New" or "Revised" License

14.24k stars 6.91k forks source link

REST API documentation #2684

Closed cebe closed 6 years ago

cebe commented 10 years ago

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://twitter.com/zdne/status/442739968654725121

lygfanye commented 10 years ago

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

cebe commented 10 years ago

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

bryglen commented 10 years ago

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

paunin commented 10 years ago

IMHO: swagger is the best practice in RF API services

fernandezekiel commented 10 years ago

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 commented 10 years ago

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

Faryshta commented 9 years ago

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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

citing @nostop8 from https://github.com/yiisoft/yii2/issues/62#issuecomment-245076528:

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 commented 6 years ago

@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 commented 6 years ago

Issue moved to https://github.com/yiisoft/yii2-rest/issues/14