CC BY
28УДК 5.13.00
Путнин В.И.
Старший программист в X5 Retail Group
ДОКУМЕНТИРОВАНИЕ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ С ПОМОЩЬЮ ЯЗЫКА ОПИСАНИЯ ИНТЕРФЕЙСОВ
Аннотация: необходимо произвести документирование программного интерфейса приложения(АПИ) с предоставлением этой документации в графическом формате с возможностью ограничения прав использования этой документации, возможностью описания всех возможных свойств существующего АПИ, версионированием и предоставлением ее в таком формате, в котором не будет отображена техническая реализации, но будет все необходимое для понимания пользования описываемого АПИ. Доступ к такой документации должен предоставляться по URL и открываться в браузере с любых технических устройств имеющих доступ в интернет. В описание АПИ должна быть включена возможность документирования методов АПИ, сконфигурированных с помощью веб фреймворков, например, таких как Spring.
Ключевые слова: АПИ, Документация ПО, Swagger, Документирование АПИ, Описание АПИ, Описание Spring.
Для решения поставленной задачи будет использоваться веб приложение написанное на языке Java, а так же исходный код этого приложения. В качестве фреймворка будет исопльзован SpringBoot, который предоставляет возможность конфигурирования методов апи и добавления маршрутизации к этим методам с помощью внутреннего механизма маршрутизации запросов между методами АПИ. В качестве ключевого инструмента для документирования методов АПИ будет использоваться Swagger, так как является одной из самых уважаемых и мощных технологий на рынке инструментов документирования программного обеспечения. В качестве системы управления зависимостей и автоматической
сборки приложения будет использоваться ОгаШе, который позволит объеденить описанные инструменты воедино.
Перед созданием документации, создадим приложение и методы АПИ для которых в дальнейшем будет создано описание.
pRestController PRequestMappingC"/a:i/nain") pRequiredArgsConstructor public class ApiController {
private final DataService dataService;
|aGetMapping(value = 1 /data", produces = MediaType.dPPI_ICdT:T0JV_JSQJV_L'AL(JE) public Data getData(pRequestBody DataRequest request) { return dataService.getData(request);
>
[3PostMapping(value = 'data", produces = HediaTyptKAPPLICATIQti^SQH„VALUE') public void postDataipRequestBody DataCreateRequest request) { dataService.postData(request);
}
}
Рис. 1 Исходный код АПИ без документации
В исходном коде представленном на рисунке 1 отсутствует какая либо документация. Для описания реализации и основного действия, которое производит каждый метод необходимо произвести описание.
Один из вариантов это создать JavaDoc документацию, которая будет выгружаться в html страницу и выгружаться на страницу сайта.
/(HI
* Получить донные,
* ЗЙЙСЙА ~■■' ■■ rta пол^чемс Зпнных
* PretУГУ; объект данные */
pGetMapping (value = I______produces =■ flediaType. APPLICA TJQN_JS0N_ L^Luf)
Data getDflta^RequebtBoriv DataRequest request) { г etupn eats -'-?rv i' e .getData(request):
У
Рис.2 Методы описаны с помощью JavaDoc
Способ представленный на рисунке 2 имеет ряд недостатков, т.к. описывает лишь ограниченный набор параметров в отличие описания с помощью Swagger.
Произведем описание с помощью аннотаций представляемых Swagger. Нам необходимо описать тип метода, ш1,параметры запроса и типы данных для параметров запроса. В первую очередь произведем документирование кодов ошибок при обращение в метод, например таких как 200, 401, 403, 404 с помощью аннотаций @ApiResponses и @ApiResponse.
Для документирования url метода и описания того, что он должен делать будет использоваться аннотация @ApiOperation. Для документирования параметров объекта запросов необходимо будет применить @ApiModelProperty с указанием значения поля для документации и свойства того, является ли это поля обязательным для передачи в метод.
@Data
public class DataRequest { @ApiModeLProperty(value = private Long id; @ApiModelProperty(value = private Long cell; @ApiModelProperty(value = private Long row;
111d данных11, required = true) "Ячейка11, required = true) "Строка11, required = true)
Рис. 3 Описание параметров запроса с помощью Swagger
После создание описания необходимо запустить веб приложения с описанным апи и перейти по url заложенному по умолчанию. В данном случае это будет 1осаШов1::8080/ар1-ёос8.Далее после перехода по url должна будет открыться страница с документацией и параметрами, которые были введены.
Рис.4 Веб страница с документацией
Как результат созданной документации мы видим всю введенную нами информацию, а также автоматически вычисленные типы данных каждого параметра запроса с учетом количества хранимых бит в поле. Так же отображен пример запроса в формате 1БОК, которым можно обратиться в метод для выполнения свойств метода АПИ.
Так же функционал данного инструмента позволяет производить версионирование и создание тегов на методы и переменные, для более гибкого управления и ориентирования в существующих методах. Встроенная система поиска позволяет искать нужные методы и переменные по подстрокам, а система создания примера запроса автоматически создает запрос с примерами полей на основании типа возвращаемого объекта, указанного в исходном коде приложения. Из достоинств данного инструмента так же можно выделить его возможность работать с любым из современных языков программирования и фреймворков, используемых для построения приложений.
СПИСОК ЛИТЕРАТУРЫ:
Основы тестирования и верификации программного обеспечения. Уч. пособие, 2-е изд. , Старолетов С.М., 2020
Проектирование веб-АР1, Лоре Арно, ДМК-Пресс, 2020 г. Универсальные принципы дизайна, Лидвелл Уильям, Холден Критина, КоЛибри, 2019
Документирование программного обеспечения. В помощь техническому писателю. Учебное пособие, Т. А. Макаровских, Ленанд, 2015
Putnin V.I.
Senior Programmer at X5 Retail Group
DOCUMENTING THE SOFTWARE USING THE INTERFACE DESCRIPTION LANGUAGE
Abstract: it is necessary to document the application programming interface (API) with the provision of this documentation in a graphical format with the possibility of restricting the rights to use this documentation, the ability to describe all possible properties of the existing API, versioning and providing it in a format in which the technical implementation will not be displayed, but there will be everything you need to understand the use of the described API. Access to such documentation should be provided via a URL and open in a browser from any technical device with Internet access. The API description should include the ability to document API methods configured using web frameworks such as Spring.
Keywords: CUI, Software Documentation, Swagger, CUI Documenting, CUI Description, Spring Description.
