Путнин В.И.
ДОКУМЕНТИРОВАНИЕ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ С ПОМОЩЬЮ ЯЗЫКА ОПИСАНИЯ ИНТЕРФЕЙСОВ *
Аннотация:
необходимо произвести документирование программного интерфейса приложения(АПИ) с предоставлением этой документации в графическом формате с возможностью ограничения прав использования этой документации, возможностью описания всех возможных свойств существующего АПИ, версионированием и предоставлением ее в таком формате, в котором не будет отображена техническая реализации, но будет все необходимое для понимания пользования описываемого АПИ. Доступ к такой документации должен предоставляться по URL и открываться в браузере с любых технических устройств имеющих доступ в интернет. В описание АПИ должна быть включена возможность документирования методов АПИ, сконфигурированных с помощью веб фреймворков, например, таких как Spring
Ключевые слова:
АПИ, Документация ПО, Swagger, Документирование АПИ, Описание АПИ, Описание Spring
Для решения поставленной задачи будет использоваться веб приложение написанное на языке Java, а так же исходный код этого приложения. В качестве фреймворка будет исопльзован SpringBoot, который предоставляет возможность конфигурирования методов апи и добавления маршрутизации к этим методам с помощью внутреннего механизма маршрутизации запросов между методами АПИ. В качестве ключевого инструмента для документирования методов АПИ будет использоваться Swagger, так как является одной из самых уважаемых и мощных технологий на рынке инструментов документирования программного обеспечения. В качестве системы управления зависимостей и автоматической сборки приложения будет использоваться Gradle, который позволит объеденить описанные инструменты воедино. В исходном коде представленном на рисунке 1 отсутствует какая либо документация. Для описания реализации и основного действия, которое производит каждый метод необходимо произвести описание. Один из вариантов это создать JavaDoc документацию, которая будет выгружаться в html страницу и выгружаться на страницу сайта. Способ представленный на рисунке 2 имеет ряд недостатков, т.к. описывает лишь ограниченный набор параметров в отличие описания с помощью Swagger. Произведем описание с помощью аннотаций представляемых Swagger. Нам необходимо описать тип метода, url,параметры запроса и типы данных для параметров запроса. В первую очередь произведем документирование кодов ошибок при обращение в метод, например таких как 200, 401, 403, 404 с помощью аннотаций @ApiResponses и @ApiResponse. Для документирования url метода и описания того, что он должен делать будет использоваться аннотация @ApiOperation. Для документирования параметров объекта запросов необходимо будет применить @ApiModelProperty с указанием значения поля для документации и свойства того, является ли это поля обязательным для передачи в метод.
Номер журнала Вестник науки №6 (39) том 1
Ссылка для цитирования:
Путнин В.И. ДОКУМЕНТИРОВАНИЕ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ С ПОМОЩЬЮ ЯЗЫКА ОПИСАНИЯ ИНТЕРФЕЙСОВ // Вестник науки №6 (39) том 1. С. 235 - 240. 2021 г. ISSN 2712-8849 // Электронный ресурс: https://www.вестник-науки.рф/article/4567 (дата обращения: 23.04.2024 г.)
Вестник науки СМИ ЭЛ № ФС 77 - 84401 © 2021. 16+