Search code examples
ruby-on-railsswaggerdocumentation

Writing general notes for API docs using swagger-docs

I am using swagger to document my Rails REST API using swagger-docs. I am able to document every method but the problem is that I want to write general guidelines() for using API. I cannot find any method that allows me to do so. Any help will be appreciated.

Something as shown in the image below:

API Overview

Solution

  • You just need to set the "Description" attribute to some appropriate text when you initially configure Swagger.

    Have a look at the first example from 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" => "[email protected]",
        "license" => "Apache 2.0",
        "licenseUrl" => "http://www.apache.org/licenses/LICENSE-2.0.html"
      }
    }
  }
})

    The example app at petstore.swagger.io shows you the general output and layout you'll get.