Swagger надає інтерактивний інтерфейс документації API, який полегшує дослідження та тестування точок доступу API. Зазвичай, Rswag генерує документацію Swagger з тестів RSpec, але якщо ви не хочете писати специфікації, ви можете вручну створити та налаштувати документацію. Цей посібник проведе вас через процес встановлення Rswag та налаштування Swagger UI без написання специфікацій.
1. Встановлення гемів Rswag
Спочатку додайте необхідні геми до вашого Gemfile:
gem 'rswag-api'
gem 'rswag-ui'
gem 'rswag-specs' # Необов'язково, якщо не використовуєте RSpec
Далі встановіть геми за допомогою:
bundle install
Після встановлення, запустіть установник Rswag для налаштування необхідних файлів:
rails g rswag:install
2. Увімкнення Swagger UI в маршрутах
Щоб увімкнути Swagger UI, додайте наступне в config/routes.rb:
mount Rswag::Ui::Engine => '/api-docs'
mount Rswag::Api::Engine => '/api-docs'
Перезавантажте ваш сервер Rails: rails s
Тепер ви можете отримати доступ до Swagger UI за адресою: http://localhost:3000/api-docs
3. Створення
swagger.yamlвручну
Оскільки ми не генеруємо документацію з тестів, потрібно створити Swagger YAML файл вручну.
Створіть файл Swagger
mkdir -p swagger/v1
touch swagger/v1/swagger.yaml
Тепер відредагуйте swagger/v1/swagger.yaml і додайте визначення вашого API:
swagger: "2.0"
info:
title: "My API"
description: "Документація API для мого Rails додатку"
version: "1.0"
paths:
/contracts:
get:
summary: "Отримати всі контракти"
tags:
- Contracts
responses:
"200":
description: "Повертає список контрактів"
schema:
type: "array"
items:
type: "object"
properties:
id:
type: "integer"
name:
type: "string"
4. Налаштування Rswag для використання статичних файлів
За замовчуванням, Rswag шукає динамічно згенеровані файли з тестів. Щоб подати статичний файл, дотримуйтесь таких кроків:
1. Відредагуйте config/initializers/rswag-ui.rb
Створіть цей файл, якщо він ще не існує, а потім додайте:
Rswag::Ui.configure do |config|
config.swagger_endpoint '/swagger/v1/swagger.yaml', 'API v1 Docs'
end
2. Перемістіть swagger.yaml до public/
mv swagger/v1/swagger.yaml public/swagger.yaml
3. Оновіть ініціалізатор для використання нового місця розташування
Відредагуйте config/initializers/rswag-ui.rb:
Rswag::Ui.configure do |config|
config.swagger_endpoint '/swagger.yaml', 'API v1 Docs'
end
5. Перезапустіть сервер Rails
Запустіть: rails s
Тепер відвідайте:
📌 http://localhost:3000/api-docs
Тепер ви повинні побачити вашу документацію API без написання тестів RSpec!
Висновок
Ви успішно налаштували документацію API Swagger в Rails за допомогою Rswag без написання тестів! 🎉
-
Переваги: Не потрібно писати специфікації, вручну контролювати документацію API.
-
Недоліки: Потрібно вручну оновлювати файл
swagger.yaml, коли API змінюється.
Якщо вам потрібна додаткова настройка, розгляньте інтеграцію генерації Swagger JSON для динамічної документації. Дайте знати, якщо у вас є запитання! 🚀
Перекладено з: Setting Up Swagger in Rails Without RSpec Using Rswag