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",
Related
I am working on swagger file, To create the authorizer in aws apigateway.But that time I 'll mention some function and api in swagger file.But it not effecting in the Apigateway.Once I deleted the stack,It will effect the APIgateway.If any changes is did that not effecting the APIgateway.Below I mentioning the template.yml file and swagger file.Please anyone will help to solve this issue.
template.yml file
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: TestApi
Resources:
ApiGateway:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
DefinitionUri: s3://devdeliforcemumbailambda/swagger-json-testapi.json
DriverDeleteF:
Type: AWS::Serverless::Function
Properties:
FunctionName: driver_delete_fun
Handler: index.handler
Runtime: nodejs8.10
CodeUri: build/authorizer.zip
Events:
GetApi:
Type: Api
Properties:
Path: /driver
Method: delete
swagger file content
{
"swagger": "2.0",
"info": {
"title": "demo"
},
"host": "rl0cg75uff.execute-api.ap-south-1.amazonaws.com",
"basePath": "/Prod",
"schemes": [
"https"
],
"paths": {
"/driver": {
"delete": {
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"security": [
{
"CognitoAuth": []
}
],
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:ap-south-1:lambda:path/2015-03-31/functions/arn:aws:lambda:ap-south-1:539977196287:function:driver_delete_fun/invocations",
"responses": {
"default": {
"statusCode": "200"
}
},
"passthroughBehavio r": "when_no_match",
"httpMethod": "POST",
"contentHandling": "CONVERT_TO_TEXT",
"type": "aws"
}
}
},
},
"securityDefinitions": {
"CognitoAuth": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"x-amazon-apigateway-authtype": "cognito_user_pools",
"x-amazon-apigateway-authorizer": {
"providerARNs": [
"arn:aws:cognito-idp:ap-south-1:539977196287:userpool/ap-south-1_6j7axGXVm"
],
"type": "cognito_user_pools"
}
},
"lambdaAuth":{
"type": "apiKey",
"name": "Authorization",
"in": "header",
"x-amazon-apigateway-authtype": "custom",
"x-amazon-apigateway-authorizer": {
"authorizerUri": "arn:aws:apigateway:ap-south-1:lambda:path/2015-03-31/functions/arn:aws:lambda:ap-south-1:539977196287:function:my-service-dev-hello/invocations",
"authorizerResultTtlInSeconds":1,
"identitySource": "method.request.header.Authorization",
"type": "request"
}
}
},
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
Cloudformation does not compare the contents of your s3 object when you specify an S3 uri in DefinitionUri. You can instead specify a relative local path and have cloudformation cli upload it for you just as it usually does with function code. Cloudformation will then use your file hash in the s3 object key, hence having different DefinitionUri and CodeUri everytime they contain changes.
Therefore, instead of having these:
DefinitionUri: s3://devdeliforcemumbailambda/swagger-json-testapi.json
CodeUri: build/authorizer.zip
do this:
DefinitionUri: ./swagger-json-testapi.json
CodeUri: ./authorizer-code-directory
What I wrote is applicable to the following: (up to date docs here)
BodyS3Location property for the AWS::ApiGateway::RestApi resource
Code property for the AWS::Lambda::Function resource
CodeUri property for the AWS::Serverless::Function resource
DefinitionUri property for the AWS::Serverless::Api resource
SourceBundle property for the AWS::ElasticBeanstalk::ApplicationVersion resource
TemplateURL property for the AWS::CloudFormation::Stack resource
Deploy your stack as follows:
aws cloudformation package --template-file template.yaml --s3-bucket devdeliforcemumbailambda --output-template-file packaged-template.yaml
aws cloudformation deploy --capabilities CAPABILITY_NAMED_IAM --stack-name test-swagger --template-file packaged-template.yaml
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 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
Inside the Swagger API Documentation there is inside the json beside the apis array a model object entry but no documentation about it. How can I use this "models" part?
{
apiVersion: "0.2",
swaggerVersion: "1.1",
basePath: "http://petstore.swagger.wordnik.com/api",
resourcePath: "/pet.{format}"
...
apis: [...]
models: {...}
}
Models are nothing but like your POJO classes in java which have variables and properties. In models section you can define your own custom class and you can refer it as data type.
If you see below
{
"path": "/pet.{format}",
"description": "Operations about pets",
"operations": [
{
"httpMethod": "POST",
"summary": "Add a new pet to the store",
"responseClass": "void",
"nickname": "addPet",
"parameters": [
{
"description": "Pet object that needs to be added to the store",
"paramType": "body",
"required": true,
"allowMultiple": false,
"dataType": "Pet"
}
],
"errorResponses": [
{
"code": 405,
"reason": "Invalid input"
}
]
}
Here in parameter section it have one parameter who's dataType is Pet and pet is defined in models as below
{
"models": {
"Pet": {
"id": "Pet",
"properties": {
"id": {
"type": "long"
},
"status": {
"allowableValues": {
"valueType": "LIST",
"values": [
"available",
"pending",
"sold"
]
},
"description": "pet status in the store",
"type": "string"
},
"name": {
"type": "string"
},
"photoUrls": {
"items": {
"type": "string"
},
"type": "Array"
}
}
}
}}
You can have nested models , for more information see Swagger PetStore example
So models are nothing but like classes.