Как и в случае со многими принципами и методологиями в веб-разработке, от технических, например, JSON API, до нетехнических, например, Методологии бережливого запуска, кажется, что общие принципы или методологии существуют в нескольких вариациях и подсознательно разрабатываются сообществом до того, как появится какая-то блестящая идея. Spark предлагает объединить варианты одним именем, которое впоследствии станет отраслевым стандартом.
Это почти верно для разработки, ориентированной на документацию (DDD), мы все годами документировали наши API с помощью Swagger или Raml. Swagger позволил разработчику создать API и четко указать все конечные точки API в одном хорошо структурированном файле (или из комментариев к коду). Любые новые маршруты, записанные в API, также потребуют обновления файла Swagger.
Итак, в этот момент вам может быть интересно, что такое DDD, если мы уже используем Swagger.
Разработка на основе документации сводится к двум основным принципам:
- Сначала проектируйте, а затем стройте
- Дизайн API должен соответствовать Спецификации OpenAPI (ранее известной как Swagger).
- Файл yaml можно разбить на множество файловых фрагментов меньшего размера с помощью swagger-chunk для лучшего управления.
- Конечным результатом разработки API должен быть файл Yaml или JSON.
- Только после того, как маршрут задокументирован, его можно построить.
2. Незадокументированная конечная точка не должна существовать
- Все маршруты должны быть задокументированы, любые другие маршруты в API могут рассматриваться как ненужные и/или опасные,
- Интерфейсный инженер должен уметь генерировать один сервисный файл с помощью таких инструментов, как swagger-js-codegen, и ему никогда не придется смотреть на код API.
Пример настройки проекта
В примере проекта должно быть 3 репозитория:
- Документация по API (файлы swagger/OpenAPI)
- Серверная часть API (например, приложение NodeJS Express)
- Фронтенд JS-приложение (например, VueJs)
Кодовая база Swagger/OpenAPI:
- В новой папке инициализируйте npm:
npm init
- Установите чванство-чанк:
npm i --save swagger-chunk
- Инициализировать базовую кодовую базу swagger-chunk:
node node_modules/swagger-chunk --init
- Теперь разрабатывайте API небольшими порциями, пока вы не будете готовы начать что-то создавать.
Автоматическая генерация файлов API интерфейса JS из файлов swagger:
- В новой папке инициализируйте npm:
npm init
- Установите swagger-codegen:
npm i --save-dev swagger-codegen
- Скопируйте файл swagger-codegen.js [ref.1] и вставьте в основание новой папки как `swagger-codegen.js` (параметры см. в readme пакета).
- Добавьте скрипт для создания файла API в ваш файл package.json eg
"build:api-file: "node ./swagger-codegen.js"
- !Совет. Вы можете оптимизировать это, внедрив файлы swagger в виде gitsubmodule во внешнее приложение.
Внутренний API с NodeJS и ExpressJS
Создание документации swagger с помощью swagger-chunk и внешнего API-файла с помощью swagger-js-codegen довольно прямолинейно и логично. Автоматизация построения маршрутов API с помощью swagger немного сложнее.
Есть несколько уже готовых вариантов:
Из-за скорости, с которой развивается ландшафт 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 );