@davidobryakov: “Настраиваем автодокументирование для express-приложений Читать полност…”

Настраиваем автодокументирование для express-приложений

Читать полностью: https://blog.kantegory.me/express-autodoc

Долгое время в express было принято использовать решения, которые довольно большую часть работы перекладывают на разработчика. Одним из самых популярных решений и по сей день является swagger-jsdoc.

Поскольку, оно является и самым проверенным, я продолжал рассказывать о нём студентам из года в год. Но в этом году что-то пошло не так... Один из студентов спросил: "а нет ли чего-то такого же удобного, как в Nest.JS?". Тут-то всё и началось.

Я прочитал более десятка статей, пересмотрел несколько роликов в поисках оптимального решения. И вот мы здесь. Я выделил 3 решения для настройки автодокументации и подготовил сравнения и примеры для них.

swagger-jsdoc

Пример кода:

/**
 * @openapi
 * /v1/testCreate:
 *   post:
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: username
 *         in: formData
 *         required: true
 *         type: string
 *       - name: password
 *         in: formData
 *         required: true
 *         type: string
 *     description: Test create
 *     responses:
 *       200:
 *         description: Returns a created object.
 */
router
  .route('/testCreate')
  .post(exampleController.post)

Полный код примера доступен на github.

Плюсы:
- простота
- универсальность

Минусы:
- много ручной работы

routing-controllers

Пример кода:

@JsonController()
export class ExampleController {
    @OpenAPI({ summary: 'Test create' })
    @ResponseSchema(TestCreateResponseDto, { statusCode: 200 })
    @Post('/testCreate')
    post(
        @Body({ type: TestCreateDto }) body: TestCreateDto,
        @Res() response: Response,
    ): void {
        const uuid: string = randomUUID();

        const responseBody = {
            uuid,
            ...body,
        };

        response.status(201).send(responseBody);
    }
}

Полный код примера доступен на github.

Плюсы:
- код более структурирован
- вынужденное использование валидаторов
- синтаксически близко к Nest

Минусы:
- проблема с рантаймом tsx
- остаётся ли express всё ещё таким же лёгким?

tsoa

Пример кода:

@Route()
@Tags('Example')
export class ExampleController extends Controller {
    @Post('/testCreate')
    @Response<TestCreateResponseDto>(201, 'Returns a created object.')
    public async post(
        @Body() body: TestCreateDto,
    ): Promise<TestCreateResponseDto> {
        const uuid: string = randomUUID();

        return {
            uuid,
            ...body,
        };
    }
}

Полный код примера доступен на github.

Плюсы:
- код более структурирован
- встроенная валидация
- комплексное решение
- синтаксически близко к Nest

Минусы:
- остаётся ли express всё ещё таким лёгким?

Выводы

Сухое сравнение доступно на npm-compare. По моим личным ощущениям, tsoa — самый оптимальный вариант.

Читать полностью: https://blog.kantegory.me/express-autodoc