I am new to right API documentation using RAML.In one example i saw a code like
resourceTypes:
- base:
get?:
responses: &standardResponses
put?:
responses: *standardResponses
post?:
responses: *standardResponses
delete?:
responses: *standardResponses
- collection:
type: base
get:
is: [showActive]
responses:
200:
body:
application/json:
schema: <<schema>>
post:
body:
application/json:
schema: <<schema>>
responses:
200:
body:
application/json:
schema: <<schema>>
So what is difference between &standardResponses and *standardResponses ?
And why we used Question mark(?) after http methods and what is the meaning when we use type: base?
&{name} - declare a block
*{name} - use the block
Simple example:
/customers:
get:
responses:
200:
headers: &commonResponseHeaders
Server-Transaction-Id:
description: Transaction id in the middleware. Can be used for debugging.
type: string
required: true
body:
example: !include examples/customers.json
schema: !include schemas/customers.json
/{customerId}:
get:
responses:
200:
description: The request was successful and a customer was found
headers: *commonResponseHeaders
404:
description: Customer was not found with `customerId = {customerId}`
headers: *commonResponseHeaders
So you don't need repeat in every response same headers.
Related
I'm trying to use Strict-Transport-Security header with API Gateway on swagger definition, but I keep getting Invalid mapping expression parameter specified: method.response.header.Strict-Transport-Security when I use:
x-amazon-apigateway-integration:
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Strict-Transport-Security: "'max-age=31536000; includeSubdomains; preload'"
Full definition below:
openapi: 3.0.1
info:
title:APIs
version: 1.0.1
servers:
- url: "http://localhost:9001"
security:
- ApiGateway: []
paths:
/user/{id}:
get:
summary: Get user
parameters:
- in: path
name: id
required: true
schema:
type: string
format: uuid
description: return user by ID
responses:
"200":
description: user returned successfully
content:
application/json:
schema:
$ref: "#/components/schemas/User"
"400":
description: Validation failure
"500":
description: Something went wrong
x-amazon-apigateway-integration:
uri:
Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${apiLambda.Arn}/invocations
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Strict-Transport-Security: "'max-age=31536000; includeSubdomains; preload'"
passthroughBehavior: "never"
httpMethod: "POST"
type: "aws_proxy"
/user:
post:
summary: Create user
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/User"
responses:
"200":
description: User created successfully
"400":
description: Validation failure
"500":
description: Something went wrong
x-amazon-apigateway-integration:
uri:
Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${apiLambda.Arn}/invocations
responses:
default:
statusCode: "200"
passthroughBehavior: "never"
httpMethod: "POST"
type: "aws_proxy"
components:
securitySchemes:
ApiGateway:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
User:
type: object
required:
- id
- name
properties:
id:
type: string
format: uuid
example: "317d0a1d-1a44-4a47-b2d8-cbe64665591c"
description: "user ID"
name:
type: string
example: "Josiah Morrow"
description: "User name"
minimum: 1
maximum: 50
Unable to put integration response on 'GET' for resource at path '/user/{id}': Invalid mapping expression specified: Validation Result: warnings : [], errors : [Invalid mapping expression parameter specified: method.response.header.Strict-Transport-Security]
I need an example for an email with some complext content(json format) and multiple array attachment. The attachments should be able to be of any format. so far I have searched everywhere and I am starting to think it may not be possible. what I would like is something like below:
/somepath:
put:
summary: sends an email
description: Send an email
operationId: send-mail
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/data.SomeData'
type: object
properties:
format: binary
attachment:
content:
multipart/form-data:
schema:
properties:
my-attachment:
type: array
items:
type: string
format: binary
This is what I have tried to do in swagger 2.0, which looks more realistic and swagger 2.0 does not accept:
/somePath:
put:
consumes:
- multipart/form-data
description: Send an email
operationId: send-mail
parameters:
- description: The Data model
in: body
name: someData
required: true
schema:
$ref: '#/definitions/data.someData'
type: object
- description: Base 64 upload attachment
in: formData
name: file
type: array
items:
type: string
format: binary
Found the Answer for Openapi 3.0 :
multipart/form-data:
schema:
type: object
properties:
body:
$ref: '#/components/schemas/data.SomeData'
file:
type: array
description: Base 64 upload attachment
items:
type: string
format: binary
required:
- body
I can't figure out what's wrong on my Authorization.
I've a Hello function which only returns a simple a static message. If I deploy without set "Authorizer", it works. I've tested on Postman. The issue starts when I try adding Authorizer.
I've my Cognito fully working. On my front end I can sign up, then do a login and then get the Token from this login session.
When I go to Postman and test, I'm always getting "unauthorized" as answers.
On Postman I test on GET method, on "Headers" tab I added "Authorization" attribute and pasted on value the token that I've from Login session. I also tested this on the value field the prefix "bearer" as some places recommended. No success.
I've been trying for the past week solve this issue. Please, any help will be extremely useful.
serverless.yml
provider:
name: aws
runtime: nodejs10.x
stage: dev
region: eu-west-1
environment:
MY_TABLE: ${self:custom.myStage}_${self:custom.settings.tb_items}
MY_STAGE: ${self:custom.myStage}
MY_DOMAIN: ${self:custom.myDomain}
iamRoleStatements:
- Effect: "Allow"
Action:
- "dynamodb:GetItem"
- "dynamodb:PutItem"
- "dynamodb:UpdateItem"
- "dynamodb:DeleteItem"
- "dynamodb:Scan"
Resource: "*"
functions:
hello:
handler: ${self:custom.pathFunc}/phraseOption.hello
events:
- http:
method: GET
path: hello
cors: true
integration: lambda-proxy
authorizer:
type: COGNITO_USER_POOLS
authorizerId:
Ref: ApiGatewayAuthorizer
resources:
Resources:
CognitoUserPool:
Type: "AWS::Cognito::UserPool"
DeletionPolicy: Retain
Properties:
MfaConfiguration: OFF
UserPoolName: ${self:custom.myStage}_aePool
EmailVerificationSubject: 'Your verification Code'
EmailVerificationMessage: 'Use this code to confirm your sign up {####}'
AutoVerifiedAttributes:
- email
UsernameAttributes:
- email
Policies:
PasswordPolicy:
MinimumLength: 6
RequireLowercase: False
RequireNumbers: False
RequireSymbols: False
RequireUppercase: False
CognitoUserPoolClient:
Type: "AWS::Cognito::UserPoolClient"
DeletionPolicy: Retain
Properties:
ClientName: ${self:custom.myStage}_aePoolClient
GenerateSecret: False
UserPoolId:
Ref: CognitoUserPool
ApiGatewayAuthorizer:
Type: AWS::ApiGateway::Authorizer
Properties:
Name: CognitoUserPool
Type: COGNITO_USER_POOLS
IdentitySource: method.request.header.Authorization
RestApiId:
Ref: ApiGatewayRestApi
ProviderARNs:
- Fn::GetAtt:
- CognitoUserPool
- Arn
phraseOptions.js
module.exports.hello = (event, context, callback) => {
const response = {
statusCode: 200,
body: JSON.stringify({
message: 'Your function executed successfully!',
input: event,
}),
};
callback(null, response);
};
I can see the function was created with the correct Auth:
Also Authorizer create as expected (I guess)
Swagger
---
swagger: "2.0"
info:
version: "2019-10-07T21:24:17Z"
title: "XXXXXX"
host: "XXXXXX"
basePath: "/dev"
schemes:
- "https"
paths:
/getPhrase:
get:
responses: {}
options:
consumes:
- "application/json"
produces:
- "application/json"
responses:
200:
description: "200 response"
headers:
Access-Control-Allow-Origin:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Credentials:
type: "string"
Access-Control-Allow-Headers:
type: "string"
/hello:
get:
responses: {}
security:
- CognitoUserPool: []
/item:
post:
responses: {}
options:
consumes:
- "application/json"
produces:
- "application/json"
responses:
200:
description: "200 response"
headers:
Access-Control-Allow-Origin:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Credentials:
type: "string"
Access-Control-Allow-Headers:
type: "string"
/item/{itemId}:
get:
responses: {}
put:
responses: {}
delete:
responses: {}
options:
consumes:
- "application/json"
produces:
- "application/json"
responses:
200:
description: "200 response"
headers:
Access-Control-Allow-Origin:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Credentials:
type: "string"
Access-Control-Allow-Headers:
type: "string"
/items:
get:
responses: {}
options:
consumes:
- "application/json"
produces:
- "application/json"
responses:
200:
description: "200 response"
headers:
Access-Control-Allow-Origin:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Credentials:
type: "string"
Access-Control-Allow-Headers:
type: "string"
securityDefinitions:
CognitoUserPool:
type: "apiKey"
name: "Authorization"
in: "header"
x-amazon-apigateway-authtype: "cognito_user_pools"
I've figure out what was wrong!
The server side was Ok. The issue on testing it on Postman was the Token.
I was using "cognitoUser.signInUserSession.accessToken.jwtToken", but supposed to be "cognitoUser.signInUserSession.idToken.jwtToken".
Everything working as expected now.
I'd like to import an open-api 3.0 yaml file into postman, v. 7.1.1.
I am generating OpenApi 3.0 docs in Laravel using darkaonline/l5-swagger. The generated open-api 3.0 yaml file produces an error-free output when pasted into editor.swagger.io. The api is being written in accordance with json:api spec (or is intended to be).
When the file is imported to postman (v 7.1.1) this error is generated : "Error while importing Open API 3.0: Could not import" All the documentation I've read says that postman now supports open api 3.0. I tried loading OpenApi 3.0 yaml examples from Zircote's github, and they imported just fine. They are much less complex than our docs, though.
Code excerpt: Warning this is a lot, but I feel like I needed to give enough context(It's actually a small chunk of the full doc--the file is 2000 lines long):
info:
title: 'NAME OF MY API'
version: 1.0.0
servers:
-
url: 'https://api.API.com/v1'
paths:
/accounts:
get:
tags:
- accounts
summary: 'list accounts'
operationId: 'App\Http\Controllers\v1\AccountsController::index'
responses:
200:
description: 'A list of accounts'
content:
application/vnd.api+json:
schema:
required:
- data
properties:
data:
description: 'Show all accounts for this request.'
type: array
items:
properties:
type:
type: string
id:
type: string
attributes:
$ref: '#/components/schemas/account'
relationships:
properties:
persons:
type: array
items:
$ref: '#/components/schemas/relationship'
type: object
links:
$ref: '#/components/schemas/relationship/properties/links'
type: object
meta:
$ref: '#/components/schemas/meta'
links:
$ref: '#/components/schemas/links'
type: object
401:
description: 'Unauthorized access'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/error-response'
404:
description: 'No records found'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/error-response'
servers:
-
url: 'https://api.API.com/v1'
post:
tags:
- accounts
summary: 'new account'
operationId: 'App\Http\Controllers\v1\AccountsController::store'
responses:
201:
description: 'Successful save'
401:
description: 'Unauthorized access'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/error-response'
400:
description: 'Bad request, save failed'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/error-response'
servers:
-
url: 'https://api.API.com/v1'
'/accounts/{id}':
get:
tags:
- accounts
summary: 'get one account'
operationId: 'App\Http\Controllers\v1\AccountsController::show'
parameters:
-
name: id
in: path
required: true
schema:
type: string
responses:
200:
description: 'An account object'
content:
application/vnd.api+json:
schema:
properties:
type:
description: 'Display the specified resource.'
type: string
id:
description: 'Display the specified resource.'
type: string
attributes:
$ref: '#/components/schemas/account'
relationships:
description: 'Display the specified resource.'
properties:
persons:
description: 'Display the specified resource.'
type: array
items:
$ref: '#/components/schemas/relationship'
type: object
links:
$ref: '#/components/schemas/relationship/properties/links'
type: object
401:
description: 'Unauthorized access'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/error-response'
404:
description: 'Record not found'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/error-response'
servers:
-
url: 'https://api.API.com/v1'
delete:
tags:
- accounts
summary: 'remove account'
operationId: 'App\Http\Controllers\v1\AccountsController::destroy'
parameters:
-
name: id
in: path
required: true
schema:
type: string
responses:
200:
description: 'An account object'
401:
description: 'Unauthorized access'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/error-response'
405:
description: 'Method not allowed'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/error-response'
400:
description: 'Bad request, save failed'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/error-response'
servers:
-
url: 'https://api.API.com/v1'
patch:
tags:
- accounts
summary: 'update account'
operationId: 'App\Http\Controllers\v1\AccountsController::update'
parameters:
-
name: id
in: path
required: true
schema:
type: string
responses:
200:
description: 'An account object'
401:
description: 'Unauthorized access'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/error-response'
400:
description: 'Bad request, save failed'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/error-response'
servers:
-
url: 'https://api.API.com/v1'
components:
schemas:
account:
title: 'account object'
description: 'A single account object.'
required:
- ur_account_id
- name
- address1
- city
- state
- zip
- country_code
- phone
- email
properties:
_id:
description: 'Unique identifier to include in path to get a single record.'
type: string
ur_account_id:
description: 'The unique account ID.'
type: string
name:
description: 'The name associated with the account'
type: string
address_1:
description: 'The street address for the account.'
type: string
address_2:
description: 'The Suite number, PO Box Number, Floor Number, etc, for the account.'
type: string
city:
description: 'The city the account is resides in.'
type: string
state:
description: 'The two letter abbreviation of the state the account resides in'
type: string
zip:
description: 'The Postal Code the account resides in.'
type: string
country_code:
description: 'Country code associated with the account.'
type: string
phone:
description: 'The phone number associated with the account.'
type: string
phone_alpha:
description: 'The phone number associated with the account.'
type: string
email:
description: 'Email associated with the account'
type: string
require_po:
description: 'Whether the account requires a PO.'
type: string
status:
description: 'Status of current account'
type: boolean
tags:
-
name: accounts
description: 'Everything about accounts'
externalDocs:
description: 'Find out more'
url: 'http://admin.API.com/documents' ```
The problem is that within each path object’s servers object, I defined only the base URL, assuming for some reason that the base URL would be concatenated with the path. If you define a server object within the path object, you have to use the FULL URL for the endpoint. It was giving me errors specifically with /{id} endpoints because I defined a path variable that not present in the servers object
I have two API calls Login and Logout.
First call (Login) is to generate Token based on user name and password.
Second call needs token generated by first call.
How I set that token for second call using Swagger 3.0 ?
I have this yaml short code line as a starting point, if you have any welcome ideas
/auth/credential/login:
post:
tags:
- Credintial login
summary: Logs in and returns the authentication cookie
description: This can only be done by the logged in user.
operationId: createUser
security: []
responses:
'200':
description: >-
Successfully authenticated.
headers:
X-RateLimit-Limit:
schema:
type: integer
description: Request limit per hour.
Set-Cookie:
schema:
type: string
description: Get token value
content:
application/json:
schema:
$ref: '#/components/schemas/Login'
x-forwarded-for:
schema:
$ref: '#/components/schemas/Login'
'202':
description: Life is hard
content:
application/json:
schema:
$ref: '#/components/schemas/LoginRespons'
x-forwarded-for:
schema:
$ref: '#/components/schemas/LoginRespons'
'405':
description: Invalid Login
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Login'
description: Created auth object
required: true
/auth/logout:
post:
tags:
- Logout
summary: Logout a user
description: ''
responses:
'200':
description: Success
content:
'*/*':
schema:
$ref: '#/components/schemas/Logout'
'202':
description: Success Logout!
content:
'*/*':
schema:
$ref: '#/components/schemas/LogoutResponse'
'405':
description: Invalid Logout
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Logout'
description: description