使用 swagger-docs 为 API 文档编写一般注释

Question

我正在使用 swagger 来记录我的 Rails REST API 使用 swagger-docs。我能够记录每种方法，但问题是我想编写使用 API 的一般指南（）。我找不到任何允许我这样做的方法。任何帮助将不胜感激。

如下图所示：

Answer 1

您只需要在初始配置 Swagger 时将 "Description" 属性设置为一些适当的文本。

看看 https://github.com/richhollis/swagger-docs 中的第一个例子：

Swagger::Docs::Config.register_apis({
  "1.0" => {
    # the extension used for the API
    :api_extension_type => :json,
    # the output location where your .json files are written to
    :api_file_path => "public/api/v1/",
    # the URL base path to your API
    :base_path => "http://api.somedomain.com",
    # if you want to delete all .json files at each generation
    :clean_directory => false,
    # add custom attributes to api-docs
    :attributes => {
      :info => {
        "title" => "Swagger Sample App",
        "description" => "This is a sample description.",
        "termsOfServiceUrl" => "http://helloreverb.com/terms/",
        "contact" => "apiteam@wordnik.com",
        "license" => "Apache 2.0",
        "licenseUrl" => "http://www.apache.org/licenses/LICENSE-2.0.html"
      }
    }
  }
})

petstore.swagger.io 中的示例应用向您展示了您将获得的一般输出和布局。

使用 swagger-docs 为 API 文档编写一般注释

Writing general notes for API docs using swagger-docs

ruby-on-rails

api

documentation

swagger