Как документировать API
10 апреля 2014 API 4 комментария 13177 просмотров
Многие разработчики до сих пор создают документацию своих API в Word или Excel. Да и сам я когда-то так делал. Пока, не нашел такой инструмент как Apiary. Вкратце, он позволяет оформить страницу API, расписать всё по полочкам, предоставить доступ другим пользователям, а самое интересное - тестировать свои API-методы.

1. Проект и его конфигурация

Для начала создадим пустой проект, достаточно нажать кнопку "Create New API". После введения названия будет сгенерирована уникальная ссылка. В нашем случае - https://app.apiary.io/myproject2. Вы спросите - "И что, любой может просматривать API?". Этот тестовый проект я сделал публичным, но в настройках можно сделать документацию приватной.

2. GitHub

Apiary старается максимально интегрировать всё с GitHub, и мне это нравится. Начиная с того, что можно логиниться через GitHub. А еще интересно то, что можно законнектить API с репозиторием, тогда изменения в API будут вызывать коммиты. Ну и изменять API можно будет не через сайт, а через файл apiary.apib.

3. Blueprint

Приступим к описанию документации. Всё API строится из текста, написанного разметкой Blueprint. Он очень похож на Markdown, думаю, разобраться в нем сможет каждый. Из чего же состоит этот файл? Сначала идут основные настройки проекта, описание и т.д. Для моего тестового проекта я написал следующее:
FORMAT: 1A
HOST: http://plutov.by/api

# MyProject
Description of my project
Далее идут уже сами методы, но для удобства их можно разбить на группы, что позволяет позже легко перемещаться по бесконечному множеству функций.
# Group Comments
All methods related to blog comments
И теперь уже добавим один метод в эту группу. Создадим метод, который будет возвращать список комментариев к посту. Тип запроса будет GET, будет передаваться ID поста. Ответом будет JSON-список комментариев.
## Get post comments [/get-comments?post_id={post_id}]
### List all Notes [GET]
+ Parameters

    + post_id (integer) ... Post ID in blog
    
+ Request (application/json)

        {
            post_id: 1000
        }

+ Response 200 (application/json)

        [
            'First comment',
            'Second comment'
        ]

4. Тестирование

Возле каждого метода есть кнопка Try It. При нажатии будет отображен запрос, заголовки и ответ. Но стоит отметить, что этот запрос будет сделан на тестовый URL и вернет он ответ, который вы описали в редакторе. Чтобы делать запросы к реальному API, вам нужно в настройках включить Proxy, тогда запрос будет идти на HOST, который вы указали в документе, в моем случае это - http://plutov.by/api.

На этом всё, пишите красивые API!
4 комментария
pekar

Александр, можно ли как-то тестировать API, когда она написано с OAuth?

@pekar, можно, но стандартного решения у Apiary нету. Суть OAuth в API заключается же в том, чтобы с каждым запросом передавать access_token. А он может получиться только пройдя процесс получения этого токена. Можно сделать небольшой хак, для тестирования создать один "вечный" токен, который будет отправляться из Apiary (в этом случае документацию было бы хорошо сделать приватной). Или же перед каждым методом вызывать процесс получения токена, а потом подставлять его в запрос. Но это не похоже на автоматизированный процесс.

Для тестирования api закрытого oauth авторизацией, есть отличный модуль для codeception http://codeception.com/docs/modules/REST

@rmrevin, спасибо за ссылку!