Документирование RESTful API
Документирование RESTful API
Какие возможности документирования RESTful API доступный сейчас?
В официальном репозитории есть обсуждение это темы: REST API documentation
Хочу собрать информацию по документированию и автодокументированию RESTful API, прошу поделится опытом или задать свои вопросы на эту тему.
В официальном репозитории есть обсуждение это темы: REST API documentation
Хочу собрать информацию по документированию и автодокументированию RESTful API, прошу поделится опытом или задать свои вопросы на эту тему.
- samdark
- Администратор
- Сообщения: 9489
- Зарегистрирован: 2009.04.02, 13:46
- Откуда: Воронеж
- Контактная информация:
Re: Документирование RESTful API
Встроенного ничего нет пока.
Нравится Yii? Давайте сделаем его лучше!.
Re: Документирование RESTful API
А есть соответствие какому либо стандарту, например спецификации Swagger 2.0?Sam Dark писал(а):Встроенного ничего нет пока.
- samdark
- Администратор
- Сообщения: 9489
- Зарегистрирован: 2009.04.02, 13:46
- Откуда: Воронеж
- Контактная информация:
Re: Документирование RESTful API
Как может быть соответствие, если у нас нет генератора?
Нравится Yii? Давайте сделаем его лучше!.
Re: Документирование RESTful API
Не ради спора, но поправьте если я неправ. Соответствие спецификации и наличие генератора это не одно и тоже.Sam Dark писал(а):Как может быть соответствие, если у нас нет генератора?
Насчет утверждения, что нет генератора, ну да генератора, который называется "I am generator RESTful API" нет, но есть gii который может сгенерировать (при наличии соответствующего шаблона) вот такой контроллер:
Этот неказистый контроллер реализует RESTful API взаимодействия с моделью app\models\User благодаря базовому классу yii\rest\ActiveController:Полное руководство по Yii 2.0 писал(а):Код: Выделить всё
namespace app\controllers; use yii\rest\ActiveController; class UserController extends ActiveController { public $modelClass = 'app\models\User'; }
Из руководства известно что получившиеся в итоге API соответствует принципам HATEOAS.Полное руководство по 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 может соответствовать каким либо спецификациям или стандартам.
Поэтому я и задал свой вопрос: А есть соответствие какому либо стандарту, например спецификации Swagger 2.0?
- samdark
- Администратор
- Сообщения: 9489
- Зарегистрирован: 2009.04.02, 13:46
- Откуда: Воронеж
- Контактная информация:
Re: Документирование RESTful API
Swagger 2.0 вроде описывает стандарт документирования, а не стандарт построения API. Это, конечно, если я не ошибаюсь.
Нравится Yii? Давайте сделаем его лучше!.
Re: Документирование RESTful API
Действительно, был не прав приводя Swagger как пример стандарт построения API.Sam Dark писал(а):Swagger 2.0 вроде описывает стандарт документирования, а не стандарт построения API. Это, конечно, если я не ошибаюсь.
- samdark
- Администратор
- Сообщения: 9489
- Зарегистрирован: 2009.04.02, 13:46
- Откуда: Воронеж
- Контактная информация:
Re: Документирование RESTful API
Я изучал вопрос и вроде как какого-то единого стандарта для API нет. Мы перед реализацией анализировали лучшие практики около 10 команд + большие API вроде Facebook или Google.
Нравится Yii? Давайте сделаем его лучше!.
Re: Документирование RESTful API
Swagger 2.0 еще не готов, на сколько я знаю
Re: Документирование RESTful API
Формат готов 8 сентября 2014 Release of Swagger 2.0 и есть альфа версия версия клиента swagger-ui@2.1.0-alpha.1 которая его поддерживает.anton44eg писал(а):Swagger 2.0 еще не готов, на сколько я знаю
Re: Документирование RESTful API
вы пробовали ей пользоваться?ilyar писал(а):Формат готов 8 сентября 2014 Release of Swagger 2.0 и есть альфа версия версия клиента swagger-ui@2.1.0-alpha.1 которая его поддерживает.anton44eg писал(а):Swagger 2.0 еще не готов, на сколько я знаю
+ видел еще изменения в стандарте
Re: Документирование RESTful API
Сформулируй свой вопрос более конкретно, что бы мой ответ был более полезным.anton44eg писал(а):вы пробовали ей пользоваться?ilyar писал(а):Формат готов 8 сентября 2014 Release of Swagger 2.0 и есть альфа версия версия клиента swagger-ui@2.1.0-alpha.1 которая его поддерживает.anton44eg писал(а):Swagger 2.0 еще не готов, на сколько я знаю
+ видел еще изменения в стандарте
В общем да пробовал, клиент 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
Re: Документирование RESTful API
это был не вопрос. пока, к сожалению, оно еще не готово для реального использования. мобильным разработчикам приходится просматривать мою документацию в swagger-editor. хотя уже 2 недели не смотрел, может лучше стало
Re: Документирование RESTful API
Уверен, если бы всезнайки стали меньше ироничными, мир стал бы немного лучше от этого.anton44eg писал(а):это был не вопрос. пока, к сожалению, оно еще не готово для реального использования. мобильным разработчикам приходится просматривать мою документацию в swagger-editor. хотя уже 2 недели не смотрел, может лучше стало
Re: Документирование RESTful API
Много воды утекло и Swagger вполне себе стал практически стандартом. Ничего не появилось пока в Yii2 для генерации документации rest?
Если не сваггер, то может RAML или Blueprint
Если не сваггер, то может RAML или Blueprint