如何使用grape-swagger将外部API文档添加到Swagger中？答案

【问题标题】：How I can add an external API documentation Into Swagger using grape-swagger?如何使用grape-swagger将外部API文档添加到Swagger中？
【发布时间】：2014-12-26 19:35:34
【问题描述】：

如何添加外部 API 文档？

例如，我正在使用门卫，POST /api/v1/token 那不是葡萄终点。如何将此端点添加到 swagger 中？

【问题讨论】：

我认为这是一个授权过程？
我在grape-swagger 上开了一个问题。他们现在没有这个功能。

标签： swagger grape grape-api

【解决方案1】：

我今天也面临同样的问题。我将 Grape 用于我的 API，并使用 Doorkeeper 作为 OAuth 2 提供者。 Doorkeeper 提供了几个 API 端点，例如POST /oauth/authorize、POST /oauth/token。

我向我的 API 添加了一个虚拟的 oauth api 类，使用 desc 和 params 描述每个端点。当然，我必须手动列出所有参数（必需或可选、名称、类型、描述、值等）。但我将实现留空。当用户调用这些 api 时，请求将被路由到 Doorkeeper 以执行实际操作。

比如我关于POST /oauth/token端点的代码：

module API
  class Oauth < Grape::API
    resources :oauth do
      # POST /oauth/token
      desc 'Requires for an access token'
      params do
        requires :grant_type,
                 type: String,
                 values: %w(client_credentials authorization_code)
        optional :code,
                 type: String
        requires :client_id,
                 type: String
        requires :client_secret,
                 type: String
        optional :redirect_uri,
                 type: String,
                 default: 'urn:ietf:wg:oauth:2.0:oob'
      end
      post :token do
      end
    end # resources :oauth

    add_swagger_documentation mount_path: 'oauth/swagger_doc',
                              api_version: '',
                              format: :json,
                              hide_format: true,
                              hide_documentation_path: true
  end
end

以及生成的招摇文档：

【讨论】：

不错，不知道grape不会覆盖门卫路由，我去测试一下。
如果你能分享他们的模板门卫oauth葡萄模板那就太棒了