https://github.com/Apipie/apipie-rails
# The simplest case: just load the paths from routes.rb
api!
def index
end
api :GET, '/users/:id'
param :id, :number
def index
end
# Most complex example
api :GET, "/users/:id", "Show user profile"
show false
error :code => 401, :desc => "Unauthorized"
error :code => 404, :desc => "Not Found", :meta => {:anything => "you can think of"}
param :session, String, :desc => "user is logged in", :required => true
param :regexp_param, /^[0-9]* years/, :desc => "regexp param"
param :array_param, [100, "one", "two", 1, 2], :desc => "array validator"
param :boolean_param, [true, false], :desc => "array validator with boolean"
param :proc_param, lambda { |val|
val == "param value" ? true : "The only good value is 'param value'."
}, :desc => "proc validator"
param :param_with_metadata, String, :desc => "", :meta => [:your, :custom, :metadata]
returns :code => 200, :desc => "a successful response" do
property :value1, String, :desc => "A string value"
property :value2, Integer, :desc => "An integer value"
property :value3, Hash, :desc => "An object" do
property :enum1, ['v1', 'v2'], :desc => "One of 2 possible string values"
end
end
description "method description"
formats ['json', 'jsonp', 'xml']
meta :message => "Some very important info"
example " 'user': {...} "
see "users#showme", "link description"
see :link => "users#update", :desc => "another link description"
def show
#...
end
https://github.com/zipmark/rspec_api_documentation
# spec/acceptance/orders_spec.rb
require 'rails_helper'
require 'rspec_api_documentation/dsl'
resource 'Orders' do
explanation "Orders resource"
header "Content-Type", "application/json"
get '/orders' do
# This is manual way to describe complex parameters
parameter :one_level_array, type: :array, items: {type: :string, enum: ['string1', 'string2']}, default: ['string1']
parameter :two_level_array, type: :array, items: {type: :array, items: {type: :string}}
let(:one_level_array) { ['string1', 'string2'] }
let(:two_level_array) { [['123', '234'], ['111']] }
# This is automatic way
# It's possible because we extract parameters definitions from the values
parameter :one_level_arr, with_example: true
parameter :two_level_arr, with_example: true
let(:one_level_arr) { ['value1', 'value2'] }
let(:two_level_arr) { [[5.1, 3.0], [1.0, 4.5]] }
context '200' do
example_request 'Getting a list of orders' do
expect(status).to eq(200)
end
end
end
put '/orders/:id' do
with_options scope: :data, with_example: true do
parameter :name, 'The order name', required: true
parameter :amount
parameter :description, 'The order description'
end
context "200" do
let(:id) { 1 }
example 'Update an order' do
request = {
data: {
name: 'order',
amount: 1,
description: 'fast order'
}
}
# It's also possible to extract types of parameters when you pass data through `do_request` method.
do_request(request)
expected_response = {
data: {
name: 'order',
amount: 1,
description: 'fast order'
}
}
expect(status).to eq(200)
expect(response_body).to eq(expected_response)
end
end
context "400" do
let(:id) { "a" }
example_request 'Invalid request' do
expect(status).to eq(400)
end
end
context "404" do
let(:id) { 0 }
example_request 'Order is not found' do
expect(status).to eq(404)
end
end
end
end
https://github.com/richhollis/swagger-docs
class Api::V1::UsersController < ApplicationController
.....
# POST /users
swagger_api :create do
summary "To create user"
notes "Implementation notes, such as required params, example queries for apis are written here."
param :form, "user[name]", :string, :required, "Name of user"
param :form, "user[age]", :integer, :optional, "Age of user"
param_list :form, "user[status]", :string, :required, "Status of user, can be active or inactive"
response :success
response :unprocessable_entity
response :500, "Internal Error"
end
def create
@user = User.new(user_params)
if @user.save
render json: @user, status: :created
else
render json: @user.errors, status: :unprocessable_entity
end
end
.....
end
https://github.com/domaindrivendev/rswag
require 'swagger_helper'
describe 'Blogs API' do
path '/blogs' do
post 'Creates a blog' do
tags 'Blogs'
consumes 'application/json', 'application/xml'
parameter name: :blog, in: :body, schema: {
type: :object,
properties: {
title: { type: :string },
content: { type: :string }
},
required: [ 'title', 'content' ]
}
response '201', 'blog created' do
let(:blog) { { title: 'foo', content: 'bar' } }
run_test!
end
response '422', 'invalid request' do
let(:blog) { { title: 'foo' } }
run_test!
end
end
end
https://github.com/fanta/rspec-rails-swagger
require 'swagger_helper'
# Paths Object
RSpec.describe "Posts Controller", type: :request do
before { Post.new.save }
# Path Item Object
path '/posts' do
# Operation Object
operation "GET", summary: "fetch list" do
# Response Object
response 200, description: "successful"
end
end
# Path Object
path '/posts/{post_id}' do
# Parameter Object
parameter "post_id", {in: :path, type: :integer}
let(:post_id) { 1 }
# Operation Object
get summary: "fetch item" do
# Response Object
response 200, description: "success"
end
end
https://github.com/Wolox/dictum
module Docs
module Pokemons
extend Dox::DSL::Syntax
document :api do # generates module Docs::Pokemons::Api
resource 'Pokemons' do
endpoint '/pokemons'
group 'Pokemons'
end
end
document :show do # generates module Docs::Pokemons::Show
action 'Get a pokemon'
end
end
end
RSpec.describe 'Pokemons', type: :request do
include Documentation::Pokemons::Api
let(:pikachu) { create(:pokemon) }
describe 'GET /pokemons/:id' do
include Documentation::Pokemons::Show
it 'gets a pokemon', :dox do
get pokemon_path(pikachu)
expect(response).to have_http_status(200)
end
end
end