1. Введение в REST API
Подходы к генерации API документации
Oleg Zinchenko
oleg@exercise.com
2. О себе
Symfony разработчик с 2009 года
TeamLead в Exercise.com
Продвигаю Symfony2 в массы
https://twitter.com/1cdecoder
https://github.com/cystbear
http://cystbear.tumblr.com/
3. Exercise.com
Программы Видео
Питание Советы тренера
Упражнения Френды, лайки
Oleg Zinchenko
4. REST
REpresentational State Transfer
Передача состояний
Over HTTP
State-less
Кеширование
Oleg Zinchenko
5. REST
ACTIONS (HTTP METHODS)
GET
POST
PUT/PATCH
DELETE
Oleg Zinchenko
6. REST
RESTful web API
GET /api/v1/orders
POST /api/v1/orders
GET /api/v1/orders/12
PUT /api/v1/orders/12
DELETE /api/v1/orders/12
GET /api/v1/orders/12/delete forbidden
Oleg Zinchenko
15. Тестирование
Behat
Buzz + aka WebApiContext
Scenario: /foods get list of food. Pagination supported.
Given I authorized as: "fred"
When I make "GET" request to the "/api/v1/foods"
Then the response status code should be: "200"
And the response body should be similar to JSON:
"""
[{"id":"4fb1fb8f944c4c0e24000622","slug":"bittermelon-cooked-a… }]
"""
Oleg Zinchenko
18. Документация
Swagger
apis: [{
path: "/pet.{format}/{petId}",
description: "Operations about pets",
operations: [{
httpMethod: "GET",
nickname: "getPetById",
responseClass: "Pet",
parameters: [...]
summary: "Find pet by its unique ID"
notes: "Only Pets which you have permission to see will be returned",
errorResponses: [...]
}]
}
http://swagger.wordnik.com/
Oleg Zinchenko
20. Документация
NelmioApiDocBundle
/**
* This the documentation description of your method, it will appear
* on a specific pane. It will read all the text until the first
* annotation.
*
* @ApiDoc(
* resource=true,
* description="This is a description of your API method",
* filters={
* {"name"="a-filter", "dataType"="integer"},
* {"name"="another-filter", "dataType"="string", "pattern"="(foo|bar) ASC|DESC"}
* }
* )
*/
public function getAction()
{
}
https://github.com/nelmio/NelmioApiDocBundle
Oleg Zinchenko