Как и в случае со многими принципами и методологиями в веб-разработке, от технических, например, JSON API, до нетехнических, например, Методологии бережливого запуска, кажется, что общие принципы или методологии существуют в нескольких вариациях и подсознательно разрабатываются сообществом до того, как появится какая-то блестящая идея. Spark предлагает объединить варианты одним именем, которое впоследствии станет отраслевым стандартом.

Это почти верно для разработки, ориентированной на документацию (DDD), мы все годами документировали наши API с помощью Swagger или Raml. Swagger позволил разработчику создать API и четко указать все конечные точки API в одном хорошо структурированном файле (или из комментариев к коду). Любые новые маршруты, записанные в API, также потребуют обновления файла Swagger.

Итак, в этот момент вам может быть интересно, что такое DDD, если мы уже используем Swagger.

Разработка на основе документации сводится к двум основным принципам:

  1. Сначала проектируйте, а затем стройте
  • Дизайн API должен соответствовать Спецификации OpenAPI (ранее известной как Swagger).
  • Файл yaml можно разбить на множество файловых фрагментов меньшего размера с помощью swagger-chunk для лучшего управления.
  • Конечным результатом разработки API должен быть файл Yaml или JSON.
  • Только после того, как маршрут задокументирован, его можно построить.

2. Незадокументированная конечная точка не должна существовать

  • Все маршруты должны быть задокументированы, любые другие маршруты в API могут рассматриваться как ненужные и/или опасные,
  • Интерфейсный инженер должен уметь генерировать один сервисный файл с помощью таких инструментов, как swagger-js-codegen, и ему никогда не придется смотреть на код API.

Пример настройки проекта

В примере проекта должно быть 3 репозитория:

  1. Документация по API (файлы swagger/OpenAPI)
  2. Серверная часть API (например, приложение NodeJS Express)
  3. Фронтенд JS-приложение (например, VueJs)

Кодовая база Swagger/OpenAPI:

  1. В новой папке инициализируйте npm: npm init
  2. Установите чванство-чанк: npm i --save swagger-chunk
  3. Инициализировать базовую кодовую базу swagger-chunk: node node_modules/swagger-chunk --init
  4. Теперь разрабатывайте API небольшими порциями, пока вы не будете готовы начать что-то создавать.

Автоматическая генерация файлов API интерфейса JS из файлов swagger:

  1. В новой папке инициализируйте npm: npm init
  2. Установите swagger-codegen: npm i --save-dev swagger-codegen
  3. Скопируйте файл swagger-codegen.js [ref.1] и вставьте в основание новой папки как `swagger-codegen.js` (параметры см. в readme пакета).
  4. Добавьте скрипт для создания файла API в ваш файл package.json eg"build:api-file: "node ./swagger-codegen.js"
  5. !Совет. Вы можете оптимизировать это, внедрив файлы swagger в виде gitsubmodule во внешнее приложение.

Внутренний API с NodeJS и ExpressJS

Создание документации swagger с помощью swagger-chunk и внешнего API-файла с помощью swagger-js-codegen довольно прямолинейно и логично. Автоматизация построения маршрутов API с помощью swagger немного сложнее.

Есть несколько уже готовых вариантов:

  1. https://github.com/krakenjs/swaggerize-express
  2. https://www.npmjs.com/package/swagger-node-express

Из-за скорости, с которой развивается ландшафт JavaScript, решение о том, создавать ли ваш API с автоматизацией маршрутов, действительно является личным выбором. Поскольку я сам не использовал ни один из этих инструментов, мне еще предстоит сформировать мнение. Как только я это сделаю, я обязательно напишу новый пост.

Заключение

Разработка на основе документации экономит время за счет автоматического создания файлов кода. Это уменьшает вероятность человеческой ошибки в плохо типизированном файле маршрутов или файле доступа к API.

К этому нужно немного привыкнуть, но как только вы сделаете 1 проект с помощью DDD, маловероятно, что вы захотите вернуться сначала к сборке, а затем к документированию.

Ссылки:

[1] Файл генератора кода Swagger:

#!/usr/bin/env node
const fs = require('fs-extra');
const { CodeGen } = require('swagger-js-codegen');
const INPUT_FILE = '../swagger-files/build/built_1.0.0.json' // << Replace this with the name of your built swagger json file.
const OUTPUT_FILE = './src/api.js';
const swagger = JSON.parse(
    fs.readFileSync(INPUT_FILE, 'utf-8')
);

const code = CodeGen.getCustomCode({
    className: 'Api',
    swagger,
});

fs.outputFileSync(
    OUTPUT_FILE,
    code
);