Question

我正在编写一个带有葡萄的API服务器，我选择使用葡萄实体，因为它有能力自动生成swagger的文档。但是，当我根据需要设置一个参数时，我有一个问题。因为葡萄不能证实参数存在。看起来葡萄忽略了实体参数的required: true。

app.rb

module Smart
  module Version1
    class App < BaseApi

      resource :app do

        # POST /app
        desc 'Creates a new app' do
          detail 'It is used to re gister a new app on the server and get the app_id'
          params  Entities::OSEntity.documentation
          success Entities::AppEntity
          failure [[401, 'Unauthorized', Entities::ErrorEntity]]
          named 'My named route'
        end
        post do
          app = ::App.create params
          present app, with: Entities::AppEntity
        end
      end
    end
  end
end

os_entity.rb

module Smart
  module Entities
    class OSEntity < Grape::Entity

      expose :os, documentation: { type: String, desc: 'Operative system name', values: App::OS_LIST, required: true }

    end
  end
end

app_entity.rb

module Smart
  module Entities
    class AppEntity < OSEntity

      expose :id, documentation: { type: 'integer', desc: 'Id of the created app', required: true }
      expose :customer_id, documentation: { type: 'integer', desc: 'Id of the customer', required: true }

    end
  end
end

其他一切现在都很好用，但我不知道如何以干燥方式使用实体，并使葡萄验证参数的要求。

Answer 1

经过一番努力，我能够让葡萄工作，因为我觉得它应该有效。因为我不想重复验证和文档的代码。你只需要将它添加到初始化器（当然，如果你在rails中）。我也能够支持嵌套关联。正如您所看到的，API代码看起来如此简单，并且swagger看起来很完美。以下是API和所有需要的实体：

应用/ API /智能/实体/ characteristics_params_entity.rb

module Smart module Entities class CharacteristicsParamsEntity < Grape::Entity root :characteristics, :characteristic expose :id, documentation: { type: Integer, desc: 'Id of the characteristic' } end end end

应用/ API /智能/实体/ characterisitcs_entity.rb

module Smart module Entities class CharacteristicsEntity < CharacteristicsParamsEntity expose :id, documentation: { type: Integer, desc: 'Id of the characteristic' } expose :name, documentation: { type: String, desc: 'Name of the characteristic' } expose :description, documentation: { type: String, desc: 'Description of the characteristic' } expose :characteristic_type, documentation: { type: String, desc: 'Type of the characteristic' } expose :updated_at, documentation: { type: Date, desc: 'Last updated time of the characteristic' } end end end

应用/ API /智能/实体/ apps_params_entity.rb

module Smart module Entities class AppsParamsEntity < Grape::Entity expose :os, documentation: { type: String, desc: 'Operative system name', values: App::OS_LIST, required: true } expose :characteristic_ids, using: CharacteristicsParamsEntity, documentation: { type: CharacteristicsParamsEntity, desc: 'List of characteristic_id that the customer has', is_array: true } end end end

应用/ API /智能/实体/ apps_entity.rb

module Smart module Entities class AppsEntity < AppsParamsEntity unexpose :characteristic_ids expose :id, documentation: { type: 'integer', desc: 'Id of the created app', required: true } expose :customer_id, documentation: { type: 'integer', desc: 'Id of the customer', required: true } expose :characteristics, using: CharacteristicsEntity, documentation: { is_array: true, desc: 'List of characteristics that the customer has' } end end end

应用/ API /智能/ VERSION1 / apps.rb

module Smart module Version1 class Apps < Version1::BaseAPI resource :apps do # POST /apps desc 'Creates a new app' do detail 'It is used to register a new app on the server and get the app_id' params Entities::AppsParamsEntity.documentation success Entities::AppsEntity failure [[400, 'Bad Request', Entities::ErrorEntity]] named 'create app' end post do app = ::App.create! params present app, with: Entities::AppsEntity end end end end end

这就是使魔法发挥作用的代码：

<强>配置/初始化/ grape_extensions.rb

class Evaluator def initialize(instance) @instance = instance end def params parameters evaluator = self @instance.normal_params do evaluator.list_parameters(parameters, self) end end def method_missing(name, *args, &block) end def list_parameters(parameters, grape) evaluator = self parameters.each do |name, description| description_filtered = description.reject { |k| [:required, :is_array].include?(k) } if description.present? && description[:required] if description[:type] < Grape::Entity grape.requires name, description_filtered.merge(type: Array) do evaluator.list_parameters description[:type].documentation, self end else grape.requires name, description_filtered end else if description[:type] < Grape::Entity grape.optional name, description_filtered.merge(type: Array) do evaluator.list_parameters description[:type].documentation, self end else grape.optional name, description_filtered end end end end end module GrapeExtension def desc name, options = {}, &block Evaluator.new(self).instance_eval &block if block super name, options do def params *args end instance_eval &block if block end end end class Grape::API class << self prepend GrapeExtension end end

这是示例的结果：

Answer 2

我喜欢用于构建API的葡萄/葡萄 - swagger /葡萄 - 实体组合。我通常使用葡萄实体来构建结果，而不是用于记录/验证API。根据文档（葡萄实体）它应该工作，但我猜测只是建立文档。

根据葡萄documentation on parameter validation and coercion，它需要block来执行任何验证/强制。

[编辑：混合参数]

您可以使用实体在desc中定义参数，但是为了进行验证，您必须提供params块，与desc块位于同一级别，例如：

    # POST /app
    desc 'Creates a new app' do
      detail 'It is used to re gister a new app on the server and get the app_id'
      params  Entities::OSEntity.documentation
      success Entities::AppEntity
      failure [[401, 'Unauthorized', Entities::ErrorEntity]]
      named 'My named route'
    end
    params do
      requires :name, String
      optional :description, String
    end 
    post do
      app = ::App.create params
      present app, with: Entities::AppEntity
    end

它们都被称为params，但位置完全不同且具有不同的功能我不确定desc块是否有除文档之外的任何用途（如何提取此文档对我来说有点神秘）。

葡萄招摇宝石不使用它，我的典型desc看起来像这样：

  desc "list of batches", {
    :notes => <<-NOTE
      Show a list of all available batches.

      ## Request properties

      * _Safe:_ Yes
      * _Idempotent:_ Yes
      * _Can be retried:_ Yes
    NOTE
  }
  params do
    optional :page, desc: 'paginated per 25'
  end
  get do
    present Batch.page(params[:page]), with: API::Entities::Batch
  end

使用markdown呈现:notes。这看起来如何在swagger-ui

葡萄：葡萄实体需要的参数

2 个答案: