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

Question

我使用swagger使用swagger-docs来记录我的Rails REST API。我能够记录每个方法，但问题是我想编写使用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处的示例应用向您展示了您将获得的常规输出和布局。