Документирование

В системе имеется механизм автоматического сбора документации в формате openAPI. Она выводится в виде HTML-страницы с помощью Swagger UI по адресу /api-docs.

Вы также можете скачать файл спецификации по URL /api-docs/download и использовать его во внешних инструментах.

Большинство методов требуют авторизации, поэтому при использовании документации сперва выполните метод User.login, а полученный JWT укажите в секции авторизации (кнопка Authorize в правом верхнем углу страницы).

Документация формируется для методов классов на основе дженериков входных и выходных параметров. Также в документацию попадает документирующий комментарий. Типы и интерфейсы, за исключением базовых типов, попадают в раздел схем документации.

Чтобы метод попал в документацию, необходимо обозначить его декоратором @OpenApi() непосредственно над функцией (после документирующего комментария).

Если параметр в дженерике будет анонимным, то есть описание объекта в фигурных скобках, то все используемые внутри собственные типы и интерфейсы будут полностью раскрыты в итоговой документации, что иногда может быть не очень удобно для чтения. Если хотите чтобы там осталось имя типа/интерфейса, создайте его и подставьте в дженерик.

Пример с анонимным типом/интерфейсом:

@OpenApi()  
async create(r: IAPIRequest<{  
   orders: ICreatePmntOrder[]  
   for_user_id?: number  
}>)

Пример с вынесенным типом/интерфейсом:

export interface ICreatePaymentRequest {  
   orders: ICreatePmntOrder[]  
   for_user_id?: number  
}

@OpenApi()  
async create(r: IAPIRequest<ICreatePaymentRequest>):

Сборка документации осуществляется командой “node ./openAPI/openApi.js”, в package.json имеется соответствующий скрипт.

Итоговый файл располагается в openAPI/swagger.yaml. Он каждый раз пересоздается, поэтому его не следует править руками.

Пожалуйста, пишите достаточный документирующий комментарий для функций. Также пишите комментарии к параметрам, если их поведение не является очевидным или не описано выше. Если вы пишите какий-нибудь модуль, желательно в начале файла расписать логику работы и граничные условия. Если по проекту ведется отдельная документация, поддерживайте ее в актуальном состоянии по согласованию с руководителем проекта/тимлидом.