gem swagger-docs 没有生成要在 swagger-ui 上显示的适当 json 文件

Question

swagger-ui 没有显示我的文档，也不知道为什么。我正在使用 swagger-docs gem，我生成了 api-docs.json，我创建了一个访问 swagger-ui 的 index.html 的路由，我将 api-docs.json 的路径作为参数传递，结果是：

swagger-ui index.html

谁能帮帮我？

config/initializers/swagger-docs.rb

Swagger::Docs::Config.base_api_controller = ActionController::API

Swagger::Docs::Config.register_apis({
  "1.0" => {
    # the extension used for the API
    :api_extension_type => :json,
    # location where our api doc files will be generated, as of now we will store files under public directory
    :api_file_path => "public/docs",
    # base path url of our application
    # while using production mode, point it to production url
    :base_path => "http://localhost:3000",
    # setting this option true tells swagger to clean all files generated in api_file_path directory before any files are generated
    :clean_directory => true,
    # As we are using Rails-API, our ApplicationController inherits ActionController::API instead of ActionController::Base
    # Hence, we need to add ActionController::API instead of default ActionController::Base
    # :base_api_controller => ActionController::API,
    # parent_controller needs to be specified if API controllers are inheriting some other controller than ApplicationController
    :parent_controller => ActionController::API,
    :attributes => {
      :info => {
        "title" => "Todos API Demo",
        "description" => "This documentation is related to Todos API",
        "contact" => "silva.danilo.nobre@gmail.com",
        "license" => "Apache 2.0",
        "licenseUrl" => "http://www.apache.org/licenses/LICENSE-2.0.html"
      }
    }
  }
})

public/docs/api-docs.json

{
  "apiVersion": "1.0",
  "swaggerVersion": "1.2",
  "basePath": "http://localhost:3000",
  "apis": [
    {
      "path": "/v2/todos.{format}",
      "description": "Todos Management"
    },
    {
      "path": "/v1/items.{format}",
      "description": "Item Management"
    },
    {
      "path": "/v1/todos.{format}",
      "description": "Todos Management"
    }
  ],
  "authorizations": null,
  "info": {
    "title": "Todos API Demo",
    "description": "This documentation is related to Todos API",
    "contact": "silva.danilo.nobre@gmail.com",
    "license": "Apache 2.0",
    "licenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.html"
  }
}

public/docs/v1/todos.json

{
  "apiVersion": "1.0",
  "swaggerVersion": "1.2",
  "basePath": "http://localhost:3000",
  "resourcePath": "todos",
  "apis": [
    {
      "path": "/todos.json",
      "operations": [
        {
          "summary": "Returns all Todos",
          "notes": "Implementation notes, such as required params, example queries for apis are written here.",
          "responseMessages": [
            {
              "code": 200,
              "responseModel": null,
              "message": "Ok"
            }
          ],
          "nickname": "V1::Todos#index",
          "method": "get"
        }
      ]
    },
    {
      "path": "/todos.json",
      "operations": [
        {
          "summary": "Create a new Todo item",
          "notes": "Notes for creating a new Todo item",
          "responseMessages": [
            {
              "code": 401,
              "responseModel": null,
              "message": "Unauthorized"
            },
            {
              "code": 406,
              "responseModel": null,
              "message": "Not Acceptable"
            },
            {
              "code": 422,
              "responseModel": null,
              "message": "Unprocessable Entity"
            }
          ],
          "parameters": [
            {
              "paramType": "form",
              "name": "todo[title]",
              "type": "string",
              "description": "Title",
              "required": true
            },
            {
              "paramType": "form",
              "name": "todo[created_by]",
              "type": "string",
              "description": "Created By",
              "required": true
            }
          ],
          "nickname": "V1::Todos#create",
          "method": "post"
        }
      ]
    },
    {
      "path": "/todos/{id}.json",
      "operations": [
        {
          "summary": "Fetches todo by id",
          "notes": "Find todo by id",
          "responseMessages": [
            {
              "code": 401,
              "responseModel": null,
              "message": "Unauthorized"
            },
            {
              "code": 406,
              "responseModel": null,
              "message": "The request you made is not acceptable"
            },
            {
              "code": 500,
              "responseModel": null,
              "message": "Requested Range Not Satisfiable"
            }
          ],
          "parameters": [
            {
              "paramType": "path",
              "name": "id",
              "type": "integer",
              "description": "Todo Id",
              "required": false
            }
          ],
          "nickname": "V1::Todos#show",
          "method": "get"
        }
      ]
    },
    {
      "path": "/todos/{id}.json",
      "operations": [
        {
          "summary": "Updates an existing Todo item",
          "responseMessages": [
            {
              "code": 401,
              "responseModel": null,
              "message": "Unauthorized"
            },
            {
              "code": 404,
              "responseModel": null,
              "message": "Not Found"
            },
            {
              "code": 406,
              "responseModel": null,
              "message": "Not Acceptable"
            }
          ],
          "parameters": [
            {
              "paramType": "path",
              "name": "id",
              "type": "integer",
              "description": "User Id",
              "required": true
            },
            {
              "paramType": "form",
              "name": "todo[title]",
              "type": "string",
              "description": "Title",
              "required": true
            },
            {
              "paramType": "form",
              "name": "todo[created_by]",
              "type": "string",
              "description": "Created By",
              "required": true
            }
          ],
          "nickname": "V1::Todos#update",
          "method": "patch"
        }
      ]
    },
    {
      "path": "/todos/{id}.json",
      "operations": [
        {
          "summary": "Deletes an existing Todo item",
          "responseMessages": [
            {
              "code": 401,
              "responseModel": null,
              "message": "Unauthorized"
            },
            {
              "code": 404,
              "responseModel": null,
              "message": "Not Found"
            }
          ],
          "parameters": [
            {
              "paramType": "path",
              "name": "id",
              "type": "integer",
              "description": "User Id",
              "required": false
            }
          ],
          "nickname": "V1::Todos#destroy",
          "method": "delete"
        }
      ]
    }
  ],
  "authorizations": null
}

Answer 1

我决定从项目中删除 swagger-docs gem 并手动创建一个 api-docs.json。因此，我可以准确地决定我的 API 可以提供哪些资源，并且变得更容易做到。选择这颗宝石对我来说不是一个好主意