如何使用快速JSON API Serializer定义与RSWAG的复杂JSON响应

发布于 2025-02-02 03:21:37 字数 1769 浏览 2 评论 0原文

我正在获得rswag设置，因此我可以轻松地为Rails API生成文档。我已经使用gem'Jsonapi-serializer'来构建响应，并且运行良好。

但是，我似乎无法弄清楚如何在RSWAG定义的schema部分中定义响应。

现在，我已经有了：

# spec/integrations/customer_spec.rb
    get 'Retrieves a customer' do
      tags 'Customers'
      produces 'application/json'
      parameter name: :id, in: :path, type: :string
      security [api_key: []]

      response '200', 'customer found' do
        schema type: :object,
          properties: {
            id: { type: :integer },
            name: { type: :string },
            email: { type: :string },
            address: { type: :json }
          },
          required: [ 'id' ]

          let(:id) { customer.public_id }

        run_test!
      end

我了解如何在上述代码示例中定义简单响应，但是我不确定如何定义更复杂的响应。

这是一个示例响应主体：

 "data"=>
  {"data"=>
    {"id"=>"cust_29od5g7d8aPuPXzb3JHfQCpzYjb",
     "type"=>"customer",
     "attributes"=>{"name"=>"Pouros, Zboncak and Bernhard", "phone"=>"+13105552474", "email"=>"[email protected]", "address"=>"13949 Janey Village, Farrellmouth, NH 73307-1612", "stripe_customer_id"=>nil, "permissions"=>{"data"=>[]}},
     "relationships"=>{"subscriptions"=>{"data"=>[]}, "products"=>{"data"=>[]}, "customer_quotas"=>{"data"=>[]}}}}}

现在，我遇到了这个错误。我不确定如何构建模式以确定id在哪里：

 Rswag::Specs::UnexpectedResponse:
       Expected response body to match schema: The property '#/' did not contain a required property of 'id' in schema 586f23d3-4484-5ad4-ad61-154265f7292b
...

原文

I'm getting rswag setup so I can easily generate documentation for my rails API. I'm already using gem 'jsonapi-serializer' to build the responses and it is working well.

However, I can't seem to figure out how to define the response in the schema section of the rswag definition.

Right now I have this:

# spec/integrations/customer_spec.rb
    get 'Retrieves a customer' do
      tags 'Customers'
      produces 'application/json'
      parameter name: :id, in: :path, type: :string
      security [api_key: []]

      response '200', 'customer found' do
        schema type: :object,
          properties: {
            id: { type: :integer },
            name: { type: :string },
            email: { type: :string },
            address: { type: :json }
          },
          required: [ 'id' ]

          let(:id) { customer.public_id }

        run_test!
      end

I understand how to define simple responses like in the above code sample, but I'm not sure how to define more complex responses.

Here's an example response body:

 "data"=>
  {"data"=>
    {"id"=>"cust_29od5g7d8aPuPXzb3JHfQCpzYjb",
     "type"=>"customer",
     "attributes"=>{"name"=>"Pouros, Zboncak and Bernhard", "phone"=>"+13105552474", "email"=>"[email protected]", "address"=>"13949 Janey Village, Farrellmouth, NH 73307-1612", "stripe_customer_id"=>nil, "permissions"=>{"data"=>[]}},
     "relationships"=>{"subscriptions"=>{"data"=>[]}, "products"=>{"data"=>[]}, "customer_quotas"=>{"data"=>[]}}}}}

Right now, I get this error. I'm not sure how to structure the schema to identify where the id is:

 Rswag::Specs::UnexpectedResponse:
       Expected response body to match schema: The property '#/' did not contain a required property of 'id' in schema 586f23d3-4484-5ad4-ad61-154265f7292b
...

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

我还不会笑 2025-02-09 03:21:37

我以前从未使用过该宝石开发，但这是JSON模式验证错误，表明该响应与您定义的架构不符。您的粘贴响应是Ruby Hash（而不是JSON），并且缺少支撑，因此很难知道您在粘贴时犯了一个错误，还是您的响应确实具有两个嵌套的“ data”;如果这不是错误，那么可能发生这样的错误的原因是在不存在的密钥级别上寻找“ ID”的规格（即，唯一键是'data'的哈希级别）。

GEM在其 readme的rspec dsl 部分和您的模式定义的第一个示例两者都表明，它希望响应的顶级密钥等于模式属性中定义的键（这意味着要摆脱前两个data级别，并且很可能有效）。如果是错字场景，但是您的响应必须包含数据 root键，则您需要调整模式或按照DSL中的示例来解析JSON +以不同的方式验证结构。

我找到Swagger.io文档（例如， https://swagger.io/doc.io/docs/specification /deficting-responses/， https：// https：// https://swagger.io/docs.io/docs /specification/data-models/dictionaries/， https://swagger.io/specification/ ）真的很有帮助；他们还有一些工具，例如 https://inspector.swagger.io/builder 。 API构建器在API客户端工具（例如失眠症或Postman）中的功能也非常有助于使用OpenAPI语法来弄清楚什么有效，什么行之有效。

我还建议您查看GEM的源代码 - 专门针对规格文件和示例应用程序；这些通常包含您在读书中找不到的语法和用法示例。