命令

• 生成文档

rake rswag

一些代码

# frozen_string_literal: truerequire '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

 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: falseparameter name: 'id', in: :path, type: :integer, description: 'id'get('show student') dotags 'students'security [ bearer_auth: []]  # security [ Bearer: []]produces 'application/json'response '401', 'need login to create' dolet(:id) { 100 }run_test!endresponse(200, 'successful') doschema type: :object,properties: {code: { type: :integer, default: 200 },message: { type: :string, default: 'ok' },data: { '$ref' => '#/components/schemas/student' }}# let(:id) { '123' }# run_test!  # 运行测试xit  # 跳过测试用例endendend
end

  path '/api/v1/pets' dopost 'Creates a pet' dotags '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' dolet(:pet) { { name: 'Dodo', status: 'available' } }run_test!endresponse '422', 'invalid request' dolet(:pet) { { name: 'foo' } }run_test!endendend