Node.js REST API с использованием Express и Swagger.

Node.js — это мощная и популярная платформа для создания веб-приложений, которая особенно хорошо подходит для создания REST API. В этом руководстве мы рассмотрим, как использовать веб-фреймворк Express и спецификацию API Swagger для создания REST API в Node.js.

Что такое ОТДЫХ?

Прежде чем мы углубимся в создание REST API, давайте кратко обсудим, что такое REST. REST расшифровывается как Representational State Transfer и представляет собой архитектурный стиль для построения распределенных систем. Системы RESTful используют HTTP для связи и обычно имеют несколько ключевых свойств:

Они используют ресурсы, идентифицированные URI, для представления состояния системы.
Они используют стандартные методы HTTP (GET, POST, PUT, DELETE и т. д.) для управления этими ресурсами.
Они используют стандартные коды ответов HTTP для обозначения успеха или неудачи.

API-интерфейсы RESTful спроектированы так, чтобы быть простыми, масштабируемыми и удобными в использовании. Они являются популярным выбором для создания веб-API, поскольку они хорошо работают с различными клиентами (веб-браузерами, мобильными приложениями, инструментами командной строки и т. д.).

Что такое Экспресс?

Express — это минималистичный веб-фреймворк для Node.js. Он предоставляет простой API для создания веб-приложений и очень популярен в сообществе Node.js. Express спроектирован так, чтобы быть гибким и непредвзятым, поэтому вы можете использовать его для создания любого типа веб-приложения, которое вы хотите.

Что такое Сваггер?

Swagger — это спецификация для описания и документирования API. Он предоставляет стандартизированный способ определения конечных точек, параметров, ответов и других деталей API. Swagger упрощает создание документации, клиентских библиотек и серверных заглушек для вашего API.

Начало работы с Экспресс

Для начала давайте создадим новый проект Node.js и установим Express:

mkdir my-api
cd my-api
npm init
npm install express

Теперь давайте создадим простое приложение Express, которое прослушивает HTTP-запросы на порту 3000:

const express = require('express')
const app = express()

app.get('/', (req, res) => {
  res.send('Hello, world!')
})

app.listen(3000, () => {
  console.log('Server started on port 3000')
})

Это приложение определяет один маршрут, который отвечает на запросы GET к корневому пути («/»), отправляя простое «Привет, мир!» сообщение. Мы запускаем приложение, вызывая app.listen() и передавая номер порта, который мы хотим прослушивать.

Создание спецификации Swagger

Теперь, когда у нас есть простое приложение Express, давайте добавим в него документацию по Swagger. Мы будем использовать пакеты swagger-ui-express и swagger-jsdoc для создания документации.

Во-первых, давайте установим пакеты:

npm install swagger-ui-express swagger-jsdoc

Далее создадим файл swagger.js в корневом каталоге нашего проекта:

const swaggerJsdoc = require('swagger-jsdoc')
const swaggerUi = require('swagger-ui-express')

const options = {
  swaggerDefinition: {
    restapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0',
      description: 'My REST API',
    },
    servers: [
      {
        url: 'http://localhost:3000',
      },
    ],
  },
  apis: ['**/*.js'],
}

const specs = swaggerJsdoc(options)

module.exports = (app) => {
  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs))
}

Этот файл определяет функцию, которая принимает приложение Express в качестве аргумента и добавляет к нему маршрут /api-docs. Когда к этому маршруту обращаются в веб-браузере, он отображает пользовательский интерфейс Swagger, который представляет собой пользовательский интерфейс для просмотра и взаимодействия с документацией API.

Объект options, переданный swaggerJsdoc, определяет некоторую базовую информацию о нашем API, включая его название, версию и описание. Он также указывает базовый URL-адрес нашего API.

Свойство apis указывает Swagger искать документацию по API во всех файлах .js в каталоге нашего проекта (включая подкаталоги).

Добавление Swagger в наше приложение Express

Теперь, когда у нас есть файл swagger.js, который генерирует документацию Swagger, давайте добавим его в наше приложение Express:

const express = require('express')
const swagger = require('./swagger')

const app = express()

app.get('/', (req, res) => {
  res.send('Hello, world!')
})

swagger(app)

app.listen(3000, () => {
  console.log('Server started on port 3000')
})

Мы добавили оператор require() для импорта файла swagger.js и добавили вызов swagger(app) после определения наших маршрутов. Это добавит маршрут /api-docs в наше приложение Express.

Определение маршрутов API

Теперь, когда у нас настроена документация Swagger, давайте определим некоторые маршруты API. Мы создадим простой CRUD API для управления набором элементов «todo».

Во-первых, давайте создадим файл todo.js в корневом каталоге нашего проекта:

let todos = []

exports.getAll = (req, res) => {
  res.send(todos)
}

exports.create = (req, res) => {
  const todo = req.body
  todos.push(todo)
  res.send(todo)
}

exports.getById = (req, res) => {
  const id = parseInt(req.params.id)
  const todo = todos.find((t) => t.id === id)
  if (!todo) {
    res.status(404).send()
  } else {
    res.send(todo)
  }
}

exports.update = (req, res) => {
  const id = parseInt(req.params.id)
  const todo = todos.find((t) => t.id === id)
  if (!todo) {
    res.status(404).send()
  } else {
    const newTodo = req.body
    todos = todos.map((t) => (t.id === id ? newTodo : t))
    res.send(newTodo)
  }
}

exports.delete = (req, res) => {
  const id = parseInt(req.params.id)
  todos = todos.filter((t) => t.id !== id)
  res.status(204).send()
}

Этот файл экспортирует несколько функций, которые определяют поведение нашего API:

getAll: возвращает список всех задач
create: создает новую задачу
getById: возвращает один элемент списка дел по идентификатору
update: обновляет задачу по идентификатору
delete: удаляет элемент списка дел по идентификатору

Мы используем массив в памяти для хранения наших задач для простоты, но вы можете легко заменить его базой данных или другим хранилищем данных.

Теперь давайте обновим наш файл app.js, чтобы определить маршруты для нашего API:

const express = require('express')
const swagger = require('./swagger')
const todo = require('./todo')

const app = express()

app.use(express.json())

app.get('/', (req, res) => {
  res.send('Hello, world!')
})

app.get('/todos', todo.getAll)
app.post('/todos', todo.create)
app.get('/todos/:id', todo.getById)
app.put('/todos/:id', todo.update)
app.delete('/todos/:id', todo.delete)

swagger(app)

app.listen(3000, () => {
console.log('Server started on port 3000')
})

Мы используем `app.use(express.json())`, чтобы включить синтаксический анализ JSON для входящих запросов, поскольку мы будем отправлять данные JSON в наших запросах и ответах API.

Затем мы определяем наши маршруты API, используя функции, экспортированные из `todo.js`.

Протестируйте API

Теперь, когда мы определили наш API, давайте протестируем его с помощью такого инструмента, как curl или Postman.

Во-первых, давайте создадим новый элемент todo:

$ curl -X POST
-H "Content-Type: application/json"
-d '{"title":"Buy milk","completed":false}'
http://localhost:3000/todos
{"title":"Buy milk","completed":false}

Это должно вернуть только что созданный элемент списка дел.

Теперь давайте получим список всех элементов todo:

$ curl http://localhost:3000/todos
[{"title":"Buy milk","completed":false}]

Это должно вернуть массив JSON, содержащий наш единственный элемент задачи.

Наконец, давайте обновим только что созданный элемент списка дел:

$ curl -X PUT
-H "Content-Type: application/json"
-d '{"title":"Buy milk and eggs","completed":true}'
http://localhost:3000/todos/1
{"title":"Buy milk and eggs","completed":true}

Это должно вернуть обновленный элемент списка дел.

Заключение

В этой статье мы рассмотрели процесс создания REST API с использованием Node.js и Express и добавили документацию в наш API с помощью платформы Swagger. Мы также показали, как тестировать API с помощью такого инструмента, как curl.

С помощью Node.js и Express вы можете сделать гораздо больше для создания мощных и масштабируемых API, но это должно стать хорошей отправной точкой. Удачи!

Node.js REST API с использованием Express и Swagger.

Что такое ОТДЫХ?

Что такое Экспресс?

Что такое Сваггер?

Похожие вопросы