Как документировать API

Многие разработчики до сих пор создают документацию своих 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: https://jooom.ru/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, который вы указали в документе.

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