【ruby on rails】rswag使用

命令

• 生成文档

rake rswag

一些代码

# 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

 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