Skip to content

1 Swagger UI

Swagger UI — это инструмент, который позволяет визуализировать и взаимодействовать с API, используя спецификацию OpenAPI. В этом примере мы рассмот

Краткое описание

рим, как использовать Swagger UI с открытым API JSONPlaceholder, который предоставляет фейковые данные для тестирования. Шаги для использования Swagger UI с JSONPlaceholder Шаг 1: Понимание JSONPlaceholder API

JSONPlaceholder предоставляет несколько конечных точек для работы с фейковыми данными. В частности, мы будем использовать конечную точку /posts, которая возвращает список постов.

Документация JSONPlaceholder: JSONPlaceholder Documentation

Шаг 2: Создание спецификации OpenAPI

Для использования Swagger UI нам нужно создать спецификацию OpenAPI для JSONPlaceholder. Вот пример спецификации для конечной точки /posts:

openapi: 3.0.0
info:
  title: JSONPlaceholder API
  description: API для получения фейковых данных
  version: 1.0.0
servers:
  - url: https://jsonplaceholder.typicode.com
paths:
  /posts:
    get:
      summary: Получить список постов
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    userId:
                      type: integer
                    id:
                      type: integer
                    title:
                      type: string
                    body:
                      type: string

Сохраните этот YAML-код в файл, например, openapi.yaml. Шаг 3: Использование Swagger UI

Теперь мы можем использовать Swagger UI для визуализации нашей спецификации OpenAPI. Для этого есть несколько способов:

Использование локального экземпляра Swagger UI:
    Скачайте Swagger UI с GitHub.
    Распакуйте архив и откройте файл index.html в текстовом редакторе.
    Найдите раздел, где указана переменная url, и замените ее на путь к вашему файлу openapi.yaml (например, file:///path/to/openapi.yaml).
    Откройте index.html в веб-браузере.

Использование онлайн-версии Swagger UI:
    Перейдите на Swagger Editor.
    Удалите содержимое редактора и вставьте вашу спецификацию OpenAPI (из openapi.yaml).
    Swagger Editor автоматически сгенерирует интерфейс Swagger UI справа.

Шаг 4: Взаимодействие с API через Swagger UI

После того как вы открыли Swagger UI, вы увидите интерфейс, который позволяет вам взаимодействовать с API:

Найдите раздел /posts и нажмите на него, чтобы развернуть.
Нажмите кнопку "Try it out", чтобы активировать возможность ввода.
Нажмите кнопку "Execute", чтобы отправить GET-запрос к /posts.
Вы увидите ответ от API, включая статус-код, заголовки и тело ответа.

Шаг 5: Анализ ответа

После выполнения запроса вы получите ответ в формате JSON, который будет содержать массив постов. Например:

json

[
  {
    "userId": 1,
    "id": 1,
    "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
    "body": "quia et suscipit\nsuscipit..."
  },
  ...
]

Заключение

Теперь вы знаете, как использовать Swagger UI для взаимодействия с API JSONPlaceholder. Вы можете использовать этот подход для любых других API, создавая соответствующую спецификацию OpenAPI и визуализируя ее с помощью Swagger UI. Это упрощает тестирование и понимание API, а также позволяет разработчикам легко взаимодействовать с конечными точками.

Swagger — это инструмент для документирования и тестирования RESTful API. Он позволяет разработчикам описывать структуру API с помощью специального формата, обычно в формате OpenAPI Specification (OAS). Swagger предоставляет интерфейс, который позволяет пользователям взаимодействовать с API, просматривать доступные эндпоинты и тестировать их.

Пример использования Swagger

  1. Описание API: Вы можете создать файл swagger.yaml или swagger.json, в котором будет описан ваш API. Вот простой пример файла swagger.yaml:
openapi: 3.0.0
info:
  title: Пример API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Получить список пользователей
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
  /users/{id}:
    get:
      summary: Получить пользователя по ID
      parameters:
        - name: id
          in: path
          required: true
          description: ID пользователя
          schema:
            type: integer
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
        '404':
          description: Пользователь не найден

  1. Использование Swagger UI: После того как вы создали файл описания API, вы можете использовать Swagger UI для визуализации и тестирования вашего API. Swagger UI позволяет загружать ваш swagger.yaml файл и предоставляет интерактивный интерфейс для работы с API.

  2. Запуск Swagger UI: Вы можете запустить Swagger UI локально, используя Docker:

docker run -p 8080:8080 -e SWAGGER_JSON=/usr/share/nginx/html/swagger.yaml -v $(pwd)/swagger.yaml:/usr/share/nginx/html/swagger.yaml swaggerapi/swagger-ui

После этого вы сможете открыть браузер и перейти по адресу http://localhost:8080, чтобы увидеть интерфейс Swagger UI, где сможете тестировать ваши эндпоинты.

Заключение

Swagger — это мощный инструмент для документирования и тестирования API, который упрощает взаимодействие между разработчиками и пользователями API.

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

Как это работает

  1. Создание API: Вы создаете серверное приложение (например, на Node.js, Python, Java и т.д.), которое реализует RESTful API. Это приложение будет обрабатывать HTTP-запросы и взаимодействовать с базой данных.

  2. Подключение к базе данных: В вашем серверном приложении вы настраиваете соединение с базой данных (например, PostgreSQL, MySQL, MongoDB и т.д.). Это может быть сделано с помощью различных библиотек и ORM (Object-Relational Mapping) инструментов.

  3. Реализация эндпоинтов: Вы создаете эндпоинты (например, /users, /users/{id}), которые будут обрабатывать запросы от клиента. Эти эндпоинты будут выполнять операции с базой данных, такие как создание, чтение, обновление и удаление данных (CRUD).

  4. Документация с помощью Swagger: Вы создаете файл Swagger (например, swagger.yaml), который описывает ваш API. Этот файл может быть загружен в Swagger UI, чтобы предоставить пользователям интерфейс для тестирования API.

  5. Тестирование через Swagger UI: Когда вы используете Swagger UI для тестирования вашего API, он отправляет HTTP-запросы к вашему серверному приложению. Ваше приложение обрабатывает эти запросы, взаимодействует с базой данных и возвращает результаты обратно в Swagger UI.

Пример

Предположим, у вас есть серверное приложение на Node.js с использованием Express и MongoDB:

const express = require('express');
const mongoose = require('mongoose');

const app = express();
app.use(express.json());

// Подключение к базе данных
mongoose.connect('mongodb://localhost:27017/mydatabase', { useNewUrlParser: true, useUnifiedTopology: true });

// Определение модели пользователя
const User = mongoose.model('User', new mongoose.Schema({
  name: String,
}));

// Эндпоинт для получения списка пользователей
app.get('/users', async (req, res) => {
  const users = await User.find();
  res.json(users);
});

// Эндпоинт для получения пользователя по ID
app.get('/users/:id', async (req, res) => {
  const user = await User.findById(req.params.id);
  if (!user) return res.status(404).send('Пользователь не найден');
  res.json(user);
});

// Запуск сервера
app.listen(3000, () => {
  console.log('Сервер запущен на http://localhost:3000');
});

В этом примере ваше приложение подключается к базе данных MongoDB и предоставляет два эндпоинта для работы с пользователями. Swagger UI будет отправлять запросы к этим эндпоинтам, и ваше приложение будет взаимодействовать с базой данных для получения данных.

Заключение

Таким образом, для работы Swagger с данными вам необходимо иметь реализованный API, который будет взаимодействовать с базой данных. Swagger UI просто предоставляет интерфейс для тестирования и документирования этого API.