命令
- 生成文档
ruby
rake rswag一些代码
ruby
# frozen_string_literal: true
require 'rails_helper'
RSpec.configure do |config|
config.swagger_root = Rails.root.join('swagger').to_s
# the root example_group in your specs, e.g. describe '...', swagger_doc: 'v2/swagger.json'
config.swagger_docs = {
# 'v1/swagger.yaml' => {
'v1/swagger.json' => {
openapi: '3.0.1',
info: {
title: 'API V1',
version: 'v1'
},
paths: {},
servers: [
{
url: 'http://{defaultHost}',
description: '本地开发',
variables: {
defaultHost: {
default: '127.0.0.1:3000'
}
}
},
{
url: 'https://{defaultHost}',
description: '测试服',
variables: {
defaultHost: {
default: 'api.xxx.com' # 默认https
}
}
}
],
components: {
securitySchemes: {
# Bearer: {
# description: 'token necessary to use API calls',
# type: :apiKey,
# name: 'X-Admin-Authorization',
# in: :header
# }
bearer_auth: {
type: :http,
scheme: :bearer,
bearerFormat: 'JWT'
}
},
schemas: {
marks: {
type: :array,
items: {
type: :object,
properties: {
date: { type: :string },
score: { type: :number },
worksheet: { type: :string }
}
}
},
importances: {
type: :array,
items: {
type: :object,
properties: {
school_id: { type: :integer },
importance: { type: :integer }
}
}
},
improvement_priorities: {
type: :array,
items: {
type: :object,
properties: {
priority: { type: :integer },
school_id: { type: :integer }
}
}
},
subtopics: {
type: :array,
items: {
type: :object,
properties: {
id: { type: :integer },
name: { type: :string },
marks: { '$ref' => '#/components/schemas/marks' },
topic_id: { type: :integer },
difficulty: { type: :integer },
consistency: { type: :number },
importances: { '$ref' => '#/components/schemas/importances' },
proficiency: { type: :number },
improvement_priorities: { '$ref' => '#/components/schemas/improvement_priorities' }
}
}
},
topics: {
type: :array,
items: {
type: :object,
properties: {
id: { type: :integer },
name: { type: :string },
strand_id: { type: :integer },
subtopics: { '$ref' => '#/components/schemas/subtopics' },
difficulty: { type: :integer },
consistency: { type: :number },
importances: { '$ref' => '#/components/schemas/importances' },
proficiency: { type: :number },
improvement_priorities: { '$ref' => '#/components/schemas/improvement_priorities' }
}
}
},
strands: {
type: :array,
items: {
type: :object,
properties: {
id: { type: :integer },
name: { type: :string },
topics: { '$ref' => '#/components/schemas/topics' }
}
}
},
latest_assessment: {
type: :object,
properties: {
name: { type: :string },
marks: { type: :integer },
date_done: { type: :string },
total_marks: { type: :integer }
}
},
subjects: {
type: :array,
items: {
type: :object,
properties: {
id: { type: :integer },
name: { type: :string },
target: { type: :integer },
strands: { '$ref' => '#/components/schemas/strands' },
latest_assessment: { '$ref' => '#/components/schemas/latest_assessment' },
overall_proficiency: { type: :integer }
}
}
},
levels: {
type: :array,
items: {
type: :object,
properties: {
id: { type: :integer },
name: { type: :string },
level: { type: :integer },
subjects: { '$ref' => '#/components/schemas/subjects' }
}
}
},
student: {
type: :object,
properties: {
id: { type: :integer },
student_id: { type: :string },
first_name: { type: :string },
last_name: { type: :string },
registration_date: { type: :string },
school_id: { type: :integer },
photo: {
type: :object,
properties: {
url: { type: :string }
}
},
overview_data: {
type: :object,
properties: {
levels: { '$ref' => '#/components/schemas/levels' }
}
}
}
},
detailed_subtopic: {
type: :object,
properties: {
code: { type: :integer, default: 200 },
message: { type: :string, default: 'ok' },
data: { '$ref' => '#/components/schemas/partial_subtopic' },
}
},
detailed_topic: {
type: :object,
properties: {
code: { type: :integer, default: 200 },
message: { type: :string, default: 'ok' },
data: {
type: :array,
items: {
type: :object,
properties: {
date: { type: :string },
proficiency: { type: :number },
contributions: { '$ref' => '#/components/schemas/partial_subtopic' },
subtopic_id: { type: :integer },
subtopic_name: { type: :string }
}
}
}
}
},
partial_subtopic: {
type: :array,
items: {
type: :object,
properties: {
date: { type: :string },
proficiency: { type: :number },
contributions: {
type: :array,
items: {
type: :object,
properties: {
score: { type: :number },
worksheet: { type: :string },
date: { type: :string }
}
}
}
}
}
}
}
}
}
}
# Defaults to json. Accepts ':json' and ':yaml'.
config.swagger_format = :json
end
ruby
path '/api/v1/students/{id}' do
# You'll want to customize the parameter types...
parameter name: :'X-Admin-Authorization', in: :header, type: :string, required: false, default: 'sdfsd'
parameter name: :page, in: :query, type: :integer, required: false
parameter name: 'id', in: :path, type: :integer, description: 'id'
get('show student') do
tags 'students'
security [ bearer_auth: []] # security [ Bearer: []]
produces 'application/json'
response '401', 'need login to create' do
let(:id) { 100 }
run_test!
end
response(200, 'successful') do
schema type: :object,
properties: {
code: { type: :integer, default: 200 },
message: { type: :string, default: 'ok' },
data: { '$ref' => '#/components/schemas/student' }
}
# let(:id) { '123' }
# run_test! # 运行测试
xit # 跳过测试用例
end
end
end
end
ruby
path '/api/v1/pets' do
post 'Creates a pet' do
tags 'Pets'
consumes 'application/json', 'application/xml'
parameter name: :pet, in: :body, schema: {
type: :object,
properties: {
name: { type: :string },
photo_url: { type: :string },
status: { type: :string }
},
required: [ 'name', 'status' ]
}
response '201', 'pet created' do
let(:pet) { { name: 'Dodo', status: 'available' } }
run_test!
end
response '422', 'invalid request' do
let(:pet) { { name: 'foo' } }
run_test!
end
end
end