GrabDuck

Как задокументировать свой API - WebAPI - Confluence

:

С WebAPI поставляется графическая консоль Swagger, которая самодокументирует внешний API. Как писать расширения API, чтобы новые методы отображались в консоли?

 

 

Если запустить WebAPI на окружении, отличающемся от production и staging (см. как указать окружение), то при открытии браузера по относительному адресу /devdoc/index.html например по http://webapi.example.com:8092/webapi-3.3/devdoc/index.html, откроется утилита Swagger-UI. Утилита выполнена на основе https://github.com/wordnik/swagger-ui, в который добавлены специфические вещи вроде работы с dev-токенами.

 

 

Swagger настроен таким образом, что все методы, аннотированные стандартными аннотациями Spring MVC (@RequestMapping), публикуются через Swagger. При этом не имеет значения, как быз задекларирован контроллер: через сканирование пакетов, через xml-описания контекстов или любым другим способом. Swagger пытается получить максимально информации из аннотаций @RequestMapping, @RequestParam, @PathVariable.

Так время исполнения WebAPI обычные комментарии javadoc недоступны (javadoc не присутствуют в скомпилированном коде) то для добавления человекочитаемого описания методов необходимо добавить ряд Swagger-специфических аннотаций из пакета com.wordnik.swagger.annotations. Документацию по этим аннотациям можно посмотреть на сайте https://github.com/wordnik/swagger-core или почитать javadoc по классам из пакета com.wordnik.swagger.annotations.

Пример аннотированного метода

    /**
     * Получение {@link com.rooxteam.webapi.model.CustomerProperty} по {@code customerId} и {@code key}
     *
     * @param customerId Идентификатор объекта {@link com.rooxteam.webapi.model.Customer}
     * @param key        Ключ проперти
     * @return Массив {@link com.rooxteam.webapi.model.CustomerProperty}. Возвращается пустой массив если {@link com.rooxteam.webapi.model.CustomerProperty} не найдены
     */
    @ApiOperation(value = "Получение CustomerProperty по идентификатору объекта Customer и ключу настройки", notes = "Требуется аутентификация." +
            "Возвращается пустой массив если CustomerProperty не найдены ")
    @RequestMapping(method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
    @PreAuthorize("isAuthenticated()")
    @ResponseBody
    public List<CustomerProperty> get(@RequestParam("customerId") @ApiParam(value = "Идентификатор объекта Customer") String customerId,
                                      @RequestParam("key") @ApiParam(value = "Ключ настройки") String key) {

Swagger строит документацию по ApiOperation, RequestMapping. ResponseBody, RequestParam, ApiParam. Не анализируются все Javadoc, PreAuthorize. 

Скриншот странички, которую создает Swagger.

Консоль активно дорабатывается, добавляются удобные инструменты для онлайн тестирования API, следите за новыми версиями.