Документирование RESTful API

Всё что касается построения API
Ответить
Аватара пользователя
ilyar
Сообщения: 9
Зарегистрирован: 2014.09.14, 13:58

Документирование RESTful API

Сообщение ilyar »

Какие возможности документирования RESTful API доступный сейчас?

В официальном репозитории есть обсуждение это темы: REST API documentation

Хочу собрать информацию по документированию и автодокументированию RESTful API, прошу поделится опытом или задать свои вопросы на эту тему.
Аватара пользователя
samdark
Администратор
Сообщения: 9489
Зарегистрирован: 2009.04.02, 13:46
Откуда: Воронеж
Контактная информация:

Re: Документирование RESTful API

Сообщение samdark »

Встроенного ничего нет пока.
Аватара пользователя
ilyar
Сообщения: 9
Зарегистрирован: 2014.09.14, 13:58

Re: Документирование RESTful API

Сообщение ilyar »

Sam Dark писал(а):Встроенного ничего нет пока.
А есть соответствие какому либо стандарту, например спецификации Swagger 2.0?
Аватара пользователя
samdark
Администратор
Сообщения: 9489
Зарегистрирован: 2009.04.02, 13:46
Откуда: Воронеж
Контактная информация:

Re: Документирование RESTful API

Сообщение samdark »

Как может быть соответствие, если у нас нет генератора?
Аватара пользователя
ilyar
Сообщения: 9
Зарегистрирован: 2014.09.14, 13:58

Re: Документирование RESTful API

Сообщение ilyar »

Sam Dark писал(а):Как может быть соответствие, если у нас нет генератора?
Не ради спора, но поправьте если я неправ. Соответствие спецификации и наличие генератора это не одно и тоже.
Насчет утверждения, что нет генератора, ну да генератора, который называется "I am generator RESTful API" нет, но есть gii который может сгенерировать (при наличии соответствующего шаблона) вот такой контроллер:
Полное руководство по Yii 2.0 писал(а):

Код: Выделить всё

namespace app\controllers;

use yii\rest\ActiveController;

class UserController extends ActiveController
{
    public $modelClass = 'app\models\User';
}
 
Этот неказистый контроллер реализует RESTful API взаимодействия с моделью app\models\User благодаря базовому классу yii\rest\ActiveController:
Полное руководство по Yii 2.0 писал(а):GET /users: получение постранично списка всех пользователей;
HEAD /users: получение метаданных листинга пользователей;
POST /users: создание нового пользователя;
GET /users/123: получение информации по конкретному пользователю с id равным 123;
HEAD /users/123: получение метаданных по конкретному пользователю с id равным 123;
PATCH /users/123 и PUT /users/123: изменение информации по пользователю с id равным 123;
DELETE /users/123: удаление пользователя с id равным 123;
OPTIONS /users: получение поддерживаемых методов, по которым можно обратится к /users;
OPTIONS /users/123: получение поддерживаемых методов, по которым можно обратится к /users/123.
Из руководства известно что получившиеся в итоге API соответствует принципам HATEOAS.
Так же в зависимости от реализации базового класса получаемом в итоге API может соответствовать каким либо спецификациям или стандартам.

Поэтому я и задал свой вопрос: А есть соответствие какому либо стандарту, например спецификации Swagger 2.0?
Аватара пользователя
samdark
Администратор
Сообщения: 9489
Зарегистрирован: 2009.04.02, 13:46
Откуда: Воронеж
Контактная информация:

Re: Документирование RESTful API

Сообщение samdark »

Swagger 2.0 вроде описывает стандарт документирования, а не стандарт построения API. Это, конечно, если я не ошибаюсь.
Аватара пользователя
ilyar
Сообщения: 9
Зарегистрирован: 2014.09.14, 13:58

Re: Документирование RESTful API

Сообщение ilyar »

Sam Dark писал(а):Swagger 2.0 вроде описывает стандарт документирования, а не стандарт построения API. Это, конечно, если я не ошибаюсь.
Действительно, был не прав приводя Swagger как пример стандарт построения API.
Аватара пользователя
samdark
Администратор
Сообщения: 9489
Зарегистрирован: 2009.04.02, 13:46
Откуда: Воронеж
Контактная информация:

Re: Документирование RESTful API

Сообщение samdark »

Я изучал вопрос и вроде как какого-то единого стандарта для API нет. Мы перед реализацией анализировали лучшие практики около 10 команд + большие API вроде Facebook или Google.
Аватара пользователя
anton44eg
Сообщения: 2716
Зарегистрирован: 2012.01.25, 13:37
Откуда: Киев

Re: Документирование RESTful API

Сообщение anton44eg »

Swagger 2.0 еще не готов, на сколько я знаю
Аватара пользователя
ilyar
Сообщения: 9
Зарегистрирован: 2014.09.14, 13:58

Re: Документирование RESTful API

Сообщение ilyar »

anton44eg писал(а):Swagger 2.0 еще не готов, на сколько я знаю
Формат готов 8 сентября 2014 Release of Swagger 2.0 и есть альфа версия версия клиента swagger-ui@2.1.0-alpha.1 которая его поддерживает.
Аватара пользователя
anton44eg
Сообщения: 2716
Зарегистрирован: 2012.01.25, 13:37
Откуда: Киев

Re: Документирование RESTful API

Сообщение anton44eg »

ilyar писал(а):
anton44eg писал(а):Swagger 2.0 еще не готов, на сколько я знаю
Формат готов 8 сентября 2014 Release of Swagger 2.0 и есть альфа версия версия клиента swagger-ui@2.1.0-alpha.1 которая его поддерживает.
вы пробовали ей пользоваться? :)
+ видел еще изменения в стандарте
Аватара пользователя
ilyar
Сообщения: 9
Зарегистрирован: 2014.09.14, 13:58

Re: Документирование RESTful API

Сообщение ilyar »

anton44eg писал(а):
ilyar писал(а):
anton44eg писал(а):Swagger 2.0 еще не готов, на сколько я знаю
Формат готов 8 сентября 2014 Release of Swagger 2.0 и есть альфа версия версия клиента swagger-ui@2.1.0-alpha.1 которая его поддерживает.
вы пробовали ей пользоваться? :)
+ видел еще изменения в стандарте
Сформулируй свой вопрос более конкретно, что бы мой ответ был более полезным.

В общем да пробовал, клиент swagger-ui@2.1.0-alpha.1 многое из формата 2.0 не поддерживает, что именно можно видеть тут https://github.com/wordnik/swagger-ui/milestones/v2.1.0
На вопрос чем версия формата 2.0 отличается от 1.2 можно получить в документе по миграции https://github.com/wordnik/swagger-spec ... tion-Guide
Аватара пользователя
anton44eg
Сообщения: 2716
Зарегистрирован: 2012.01.25, 13:37
Откуда: Киев

Re: Документирование RESTful API

Сообщение anton44eg »

это был не вопрос. пока, к сожалению, оно еще не готово для реального использования. мобильным разработчикам приходится просматривать мою документацию в swagger-editor. хотя уже 2 недели не смотрел, может лучше стало
Аватара пользователя
ilyar
Сообщения: 9
Зарегистрирован: 2014.09.14, 13:58

Re: Документирование RESTful API

Сообщение ilyar »

anton44eg писал(а):это был не вопрос. пока, к сожалению, оно еще не готово для реального использования. мобильным разработчикам приходится просматривать мою документацию в swagger-editor. хотя уже 2 недели не смотрел, может лучше стало
Уверен, если бы всезнайки стали меньше ироничными, мир стал бы немного лучше от этого.
remizyaka
Сообщения: 5
Зарегистрирован: 2017.02.20, 17:33

Re: Документирование RESTful API

Сообщение remizyaka »

Много воды утекло и Swagger вполне себе стал практически стандартом. Ничего не появилось пока в Yii2 для генерации документации rest?
Если не сваггер, то может RAML или Blueprint
Аватара пользователя
samdark
Администратор
Сообщения: 9489
Зарегистрирован: 2009.04.02, 13:46
Откуда: Воронеж
Контактная информация:

Re: Документирование RESTful API

Сообщение samdark »

Нет, не появилось.
Ответить