require 'swagger_helper'
RSpec.describe 'Api::V1::Posts', type: :request do
path '/api/v1/posts' do
get 'Retrieves all posts' do
tags 'Posts'
produces 'application/json'
parameter name: :page, in: :query, type: :integer, required: false
parameter name: :per_page, in: :query, type: :integer, required: false
response '200', 'posts found' do
schema type: :array,
items: {
type: :object,
properties: {
id: { type: :integer },
title: { type: :string },
excerpt: { type: :string },
author: {
type: :object,
properties: {
id: { type: :integer },
name: { type: :string }
}
}
}
}
run_test!
end
end
post 'Creates a post' do
tags 'Posts'
consumes 'application/json'
produces 'application/json'
security [bearer_auth: []]
parameter name: :post, in: :body, schema: {
type: :object,
properties: {
title: { type: :string },
body: { type: :string },
tags: { type: :array, items: { type: :string } }
},
required: ['title', 'body']
}
response '201', 'post created' do
run_test!
end
response '422', 'invalid request' do
run_test!
end
end
end
end
Auto-generated API documentation from code annotations keeps docs in sync with implementation and reduces maintenance burden. The rswag gem generates OpenAPI 3.0 specs from RSpec request specs, providing interactive documentation via Swagger UI. I write request specs that describe expected inputs, outputs, and status codes, and rswag generates the corresponding OpenAPI schema. This approach serves triple duty: automated tests, documentation, and client SDK generation. The generated docs include example requests/responses, authentication requirements, and validation rules. I host Swagger UI at /api-docs in staging environments so frontend developers can explore endpoints interactively. The key is maintaining discipline around keeping specs comprehensive and up-to-date.
