菜单
Generate or update the OpenAPI specification from the Rails application tests (specs). Use when you need to synchronize the public API contract with the actual implementation in the Rails service.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Perform repository documentation accuracy audits that compare docs claims to current-branch runtime code truth and produce a dated report in docs/audit with mandatory Sections A-E, severity-ranked findings, score, and PASS/FAIL gate. Use when asked to audit root/docs markdown accuracy, generate recurring audit reports, validate setup/API contract documentation, or produce evidence-backed documentation backlog items.
Create, refresh, or reconcile the repository root `AGENTS.md` using current branch truth. Use when Codex needs to update `AGENTS.md` after code, config, CI, audit, or documentation changes, or when the repo's agent guidance must be checked against current files without widening scope to the rest of the docs set.
Create or update `docs/features/*` documentation for this repository using the established feature-doc structure and keep `docs/features/README.md` synchronized. Use when Codex needs to add a new feature page, revise an existing feature page, choose the correct feature category (`core`, `infrastructure`, `resilience`, `security`), or reconcile the features index with the files that actually exist on disk.
Create and update technical research papers in docs/research using the repository's standard structure: Problem Statement, Alternatives Considered, Trade-offs, Why Current Approach Was Selected, Benchmarks / Status, References, and Assumptions. Use when asked to write or revise architecture/implementation research notes, compare design options, or document evidence-backed rationale in this repo.
| name | generate-rails-openapi |
| description | Generate or update the OpenAPI specification from the Rails application tests (specs). Use when you need to synchronize the public API contract with the actual implementation in the Rails service. |
Use this skill to automatically generate an OpenAPI specification by running the RSpec integration tests. This ensures that the documentation accurately reflects the behavior of the API.
rails-app)spec/requests/rswag gems (rswag-api, rswag-ui, rswag-specs) installed in the Rails appEnsure dependencies are installed:
cd rails-app
bundle install
Run tests with OpenAPI generation:
Execute the RSpec tests using the Rswag task. This will run the specs and generate the Swagger file based on the path, post, response, etc. blocks.
cd rails-app
# Generate Swagger documentation
bundle exec rake rswag:specs:swaggerize
Locate the generated spec:
By default, the spec is generated at swagger/v1/swagger.yaml (as configured in spec/swagger_helper.rb).
Review:
Review the generated swagger.yaml to ensure it correctly captures the API behavior.
Gem: rswag is used to capture request/response data and generate the UI.
Helper: spec/swagger_helper.rb configures the output path and global metadata (title, version, servers).
Test Inclusion: Ensure request specs use type: :request and follow the Rswag DSL.
# spec/requests/api/v0/my_spec.rb
require 'swagger_helper'
RSpec.describe 'api/v0/my_resource', type: :request do
path '/api/v0/my_resource' do
post 'Creates a resource' do
tags 'MyResource'
consumes 'application/json'
parameter name: :resource, in: :body, schema: { ... }
response '201', 'resource created' do
run_test!
end
end
end
end
No examples found: Ensure you are running rake rswag:specs:swaggerize and that your specs use the Rswag DSL (path, response, etc.).
Database Errors: Ensure a test database is available or mocked. The app may require AWS_REGION and DB_IAM_AUTH=false for local tests.
Schema Drift: We use a shared example swagger_schema_drift_detection to ensure models and their to_swagger_schema definitions stay in sync. Run these via:
bundle exec rspec spec/models