I am using Swagger for the first time and I can't get the details of individual endpoints to show up in the json response within a resource.
Simplified, I have:
# api.rb
require 'grape-swagger'
module API
class Base < Grape::API
version 'v1', using: :path
format :json
resource :items do
desc 'Operations about items'
get '/:id' do
desc 'retrieve data for a single item'
# do something here
end
end
end
In the output, I would expect to see something like:
{
"apiVersion": "0.1",
"swaggerVersion": "1.2",
"produces":
[
"name": "application/json",
],
"resources":
[
{
"name": "items",
"description": "Operations about items",
"apis": [
{
"path": "/items/:id.{format}",
"description": "retrieve data for a single item"
}
]
}
]
}
Instead I get:
{
"apiVersion": "0.1",
"swaggerVersion": "1.2",
"produces":
[
"application/json"
],
"apis":
[
{
"path": "/items.{format}",
"description": "Operations about items"
}
]
}
what am I doing wrong? (using Rails 4.2, Ruby 2.1)
You have to mount the resource first
mount Items
Related
I've copy swagger.json file from one of the service and want to import it into Postman collection
Then the problem is I want to add custom API-key in header for every requests.
I've read about securityDefinitions but it doesn't seems to work
Let's say it's name is myCustomAPIKey, Is there a way that I can add it manually in swagger's JSON file ?
Its normal to do it like the following snippet. You create af securityDefinition and then use that definition in the security section.
{
"swagger": "2.0",
"info": {
"title": "API",
"version": "1.0"
},
"host": "example.com",
"basePath": "/api",
"schemes": [
"http",
"https"
],
"securityDefinitions": {
"myCustomAPIKey": {
"type": "apiKey",
"name": "myCustomAPIKey",
"in": "header"
}
},
"security": [
{
"myCustomAPIKey": []
}
],
"paths": {...}
}
Its documented here (for version 2) https://swagger.io/docs/specification/2-0/authentication/api-keys/
I am using Swagger-ui version 3.0.2, I have hosted it locally and provided it my Json file and API it opens the document fine and lists all the method in the json file, after i put basic authentication in it, i did changes in the .JSON file, but there are some methods which i want to mark anonymous.
{
"swagger": "2.0",
"info": {
"description": "description",
"version": "1.0",
"title": "API"
},
"host": "localhost",
"schemes": [
"http"
],
"securityDefinitions": {
"anonymous_auth": {
"type": ""
},
"basic_auth": {
"type": "basic",
"name": "basic_auth",
"description": "Basic Authentication"
},
"token": {
"type": "apiKey",
"description": "API Token Authentication",
"name": "apikey",
"in": "header"
}
},
"security": [
{
"basic_auth": [ ]
},
{
"token": [ ]
}
],
"paths": {
//somthing
},
"definitions": {
//something
}
}
By using security atribute in this way it will secure complete file, but i have some methods which should be anonymous.
To remove global security, add an empty security array to the operation:
"paths": {
"/something:": {
"get": {
"security": [],
...
}
}
}
Also, your spec is not valid:
Remove anonymous_auth.
Remove name from basic_auth - name is only used in apiKey security schemes to specify the name of the header or query parameter that will contain the API key.
My swagger index DSL is responding with the api/v1/users.json generated from rake swagger:docs.
Api::V1::UsersController:
swagger_api :index do
summary 'Returns list of users'
notes '/api/v1/users'
end
def index
#users = User.all
render(json: { users: ActiveModel::ArraySerializer.new(#users, each_serializer: Api::V1::UserSerializer) })
end
And when I try go the the actual api documentation and run /api/v1/users.json call ("Try it out!"), I get the public api definition for the whole users api controller:
{
"apiVersion": "1.0",
"swaggerVersion": "1.2",
"basePath": "http://localhost:3000",
"resourcePath": "users",
"apis": [
{
"path": "/api/v1/users.json",
"operations": [
{
"summary": "Returns list of users",
"notes": "/api/v1/users",
"nickname": "Api::V1::Users#index",
"method": "get"
}
]
},
{
"path": "/api/v1/users/{id}.json",
"operations": [
{
"summary": "Returns a user",
"notes": "/api/v1/users/:id",
"parameters": [
{
"paramType": "path",
"name": "id",
"type": "integer",
"description": "User Id",
"required": false
}
],
"nickname": "Api::V1::Users#show",
"method": "get"
}
]
}
],
"authorizations": null
}
Also, when I try the call in Postman, it returns an array of Users like I would expect.
I was wondering if anyone's done this before where they generate API docs using Swagger UI for an API not also generated by Swagger. Here's what a simple example of mine looks like:
class Api::V1::UsersController < Api::V1::BaseController
swagger_controller :users, 'Users'
swagger_api :show do
summary 'Returns a user'
param :path, :id, :integer, :optional, "User Id"
notes '/api/v1/users/:id'
response :ok, "Success", :Users
response :unauthorized
response :not_acceptable
response :not_found
end
def show
user = User.find(params[:id])
render(json: Api::V1::UserSerializer.new(user).to_json)
end
end
I've generated the swagger docs with rake swagger:docs and can reach http://localhost:3000/api-docs.json just fine where I see the documentation for Users#show, but when I click "Try it out!", I get a missing template error for api/v1/users/show
api-docs.json:
{
"apiVersion": "1.0",
"swaggerVersion": "1.2",
"basePath": "http://localhost:3000",
"apis": [
{
"path": "/api/v1/users.{format}",
"description": "Users"
}
],
"authorizations": null
}
users.json:
{
"apiVersion": "1.0",
"swaggerVersion": "1.2",
"basePath": "http://localhost:3000",
"resourcePath": "users",
"apis": [
{
"path": "/api/v1/users/{id}.json",
"operations": [
{
"summary": "Returns a user",
"parameters": [
{
"paramType": "path",
"name": "id",
"type": "integer",
"description": "User Id",
"required": false
}
],
"notes": "/api/v1/users/:id",
"responseMessages": [
{
"code": 200,
"responseModel": "Users",
"message": "Success"
},
{
"code": 401,
"responseModel": null,
"message": "Unauthorized"
},
{
"code": 404,
"responseModel": null,
"message": "Not Found"
},
{
"code": 406,
"responseModel": null,
"message": "Not Acceptable"
}
],
"nickname": "Api::V1::Users#show",
"method": "get"
}
]
}
],
"authorizations": null
}
How can I render the correct response for my show method so that it looks for the serialized json rather than a view file?
So, I found the answer. First, delete all the json files created by rake swagger:docs and add into the swagger_docs.rb initializer the following: :clean_directory => true so that everytime rake swagger:docs is run, the directory in public folder is cleared.
In order for swagger docs to work with how I'm building my API with ActiveModel's Serializers is to change up the DSL written in Api::V1::UsersController, like so:
swagger_api :show do
summary 'Returns a user'
param :path, :id, :integer, :optional, "User Id"
notes '/api/v1/users/:id'
end
then run rake swagger:docs and the call to show a user should work fine.
I am documenting the API's of my ROR application using Swagger. This is my initializer file:
class Swagger::Docs::Config
def self.transform_path(path, api_version)
# Make a distinction between the APIs and API documentation paths.
"/apidocs/#{path}"
end
end
Swagger::Docs::Config.register_apis({
'1.0' => {
controller_base_path: '',
api_file_path: 'public/apidocs',
base_path: 'http://localhost:3000',
clean_directory: true
}})
when i run the rake task,the api-docs.json wil generate for swagger GUI.
{
"apiVersion": "1.0",
"swaggerVersion": "1.2",
"basePath": "http://localhost:3000/",
"apis": [
{
"path": "/apidocs/api/v1/users.{format}",
"description": "UserS"
}]}
But the respective JSON generated for users.json,the path is not coming out correctly.
{
"apiVersion": "1.0",
"swaggerVersion": "1.2",
"basePath": "http://localhost:3000/",
"resourcePath": "users",
"apis": [
{
"path": "api/v1/users",
"operations": [
{
"summary": "Fetches all User items",
"notes": "This lists all the active users",
"parameters": [
{.....} ]}]}]}
Instead of "path": "api/v1/users", I need to get "path": "/api/v1/users",