I check out the latest code from Swagger UI 3.25.0 on github and add some features like saving and loading requet data. It works fine with Swagger 2.0 doc which has a json file like this
{
"swagger":"2.0",
"info":{
"version":"1.0",
"title":"Order api",
"description":"Order api"
},
"paths":{
"/api/v1/internal/orderdispatch/DispatchOrder/DispatchOrdersByIdList":{
"post":{
"tags":[
"Myaz.OrderDispatch.API.Controllers/DispatchOrder"
],
"operationId":"POST_api_v1_internal_orderdispatch_DispatchOrder_DispatchOrdersByIdList",
"consumes":[
"application/json-patch+json",
"application/json",
"text/json",
"application/*+json"
],
"produces":[
"application/json"
],
"parameters":[
{
"name":"salesOrderIdList",
"in":"body",
"required":false,
"schema":{
"uniqueItems":false,
"type":"array",
"items":{
"type":"string"
}
}
}
],
"responses":{
"200":{
"description":"Success"
}
},
"deprecated":false
}
},
}
}
But it seems that it can't open the OAS 3.0 doc which has the following structure.
{
"openapi": "3.0.1",
"info": {
"title": "My API",
"version": "v1"
},
"paths": {
"/api/v1/OrderRouter/SalesOrder/CreateSalesOrder": {
"post": {
"tags": [
"SalesOrder"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Myaz.ERP.Model.OrderRouter.ViewModel.SalesOrderViewModel"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Myaz.ERP.Model.OrderRouter.ViewModel.SalesOrderViewModel"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/Myaz.ERP.Model.OrderRouter.ViewModel.SalesOrderViewModel"
}
}
}
},
"responses": {
"200": {
"description": "Success"
}
}
}
},
}
}
Currently I'm using asp.net core 3.1 which only support OAS doc. So how can I use swagger UI to show OAS 3.0 doc?
Thanks in advance.
Related
Is it possible to provide a response example that is an object with an array attribute and a string attribute?
I have the following OpenAPI 3 definition:
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"examples": {
"results": [
{
"abc": 20
}
],
"totalCount": 69
},
"schema": {
"results":"array",
"totalCount": "integer"
}
}
}
}
}
But Swagger UI shows an error when I put "totalCount": 69 inside the examples object.
Change examples (plural) to example (singular), and also provide a proper schema for the response.
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"example": {
"results": [
{
"abc": 20
}
],
"totalCount": 69
},
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"abc": {
"type": "integer"
}
}
}
},
"totalCount": {
"type": "integer"
}
}
}
}
}
}
}
I'm learning about OpenApi. I'm getting this error from Swagger:
TypeError: O is undefined
value parameter-row.jsx:149
render root-injects.jsx:93
React 8
_renderValidatedComponentWithoutOwnerOrContext
_renderValidatedComponent
performInitialMount
mountComponent
mountComponent
mountChildren
_createInitialChildren
mountComponent
root-injects.jsx:95:14
My json data is:
{
"components": {
"parameters": {
"q": {
"in": "query",
"name": "q",
"style": "form"
}
}
},
"info": {
"title": "OpenWeatherMap API"
},
"openapi": "3.0.2",
"paths": {
"/weather": {
"get": {
"parameters": [
{
"$ref": "#/components/parameters/q"
}
]
}
}
}
}
Your API definition is missing some required keywords. If you paste it into https://editor.swagger.io it will show where the errors are.
Specifically, the q parameter is missing the schema (data type definition).
Here's the correct version:
{
"components": {
"parameters": {
"q": {
"in": "query",
"name": "q",
"style": "form",
"schema": {
"type": "string"
}
}
}
},
"info": {
"title": "OpenWeatherMap API",
"version": "1.0.0"
},
"openapi": "3.0.2",
"paths": {
"/weather": {
"get": {
"parameters": [
{
"$ref": "#/components/parameters/q"
}
],
"responses": {
"200": {
"description": "ok"
}
}
}
}
}
}
I have a .NET solution that uses a SAM template to generate cloudformation to deploy the stack. I am expecting the deployment - once complete - to have API Key Required = true on at least one of the methods. However after deployment, the keys and usage plans are created, but in the console the api key required is still set to false?
See below:
My SAM template:
"ServerlessRestApi": {
"Type": "AWS::ApiGateway::RestApi",
"Properties": {
"Description":"This is a placeholder for the description of this web api",
"Body": {
"info": {
"version": "1.0",
"title": {
"Ref": "AWS::StackName"
}
},
"x-amazon-apigateway-api-key-source": "HEADER",
"paths": {
"datagw/general/table/get/{tableid}": {
"get": {
"x-amazon-apigateway-integration": {
"httpMethod": "POST",
"type": "aws_proxy",
"uri": {
"Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${GetTableResponse.Arn}/invocations"
}
},
"responses": {}
},
"security":[
{
"api_key":[]
}
]},
"securityDefinitions":{
"api_key":{
"type":"apiKey",
"name":"x-api-key",
"in":"header"
}
},
"/": {
"get": {
"x-amazon-apigateway-integration": {
"httpMethod": "POST",
"type": "aws_proxy",
"uri": {
"Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${Get.Arn}/invocations"
}
},
"responses": {}
}
},
"/tables/{tableid}/{columnid}": {
"get": {
"x-amazon-apigateway-integration": {
"httpMethod": "POST",
"type": "aws_proxy",
"uri": {
"Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${GetTableBasic.Arn}/invocations"
}
},
"responses": {}
}
}
},
"swagger": "2.0"
}
}
},
I am not that familiar with swagger definitions, I know only the basics of SAM and CloudFormation. What am I missing here? I have reviewed other answers on stack overflow and believe I've copied the configuration correctly.
When I check the generated CloudFormation, my entries regarding x-api-key are not even present in the template?
"ServerlessRestApi": {
"Type": "AWS::ApiGateway::RestApi",
"Properties": {
"Body": {
"info": {
"version": "1.0",
"title": {
"Ref": "AWS::StackName"
}
},
"paths": {
"datagw/general/table/get/{tableid}": {
"get": {
"x-amazon-apigateway-integration": {
"httpMethod": "POST",
"type": "aws_proxy",
"uri": {
"Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${GetTableResponse.Arn}/invocations"
}
},
"responses": {}
}
},
"/datagw/general/webhook/ccnotify": {
"post": {
"x-amazon-apigateway-integration": {
"httpMethod": "POST",
"type": "aws_proxy",
"uri": {
"Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PostClickCollectNotification.Arn}/invocations"
}
},
"responses": {}
}
},
"/": {
"get": {
"x-amazon-apigateway-integration": {
"httpMethod": "POST",
"type": "aws_proxy",
"uri": {
"Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${Get.Arn}/invocations"
}
},
"responses": {}
}
},
"/tables/{tableid}/{columnid}": {
"get": {
"x-amazon-apigateway-integration": {
"httpMethod": "POST",
"type": "aws_proxy",
"uri": {
"Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${GetTableBasic.Arn}/invocations"
}
},
"responses": {}
}
},
"/datagw/general/post/sohupdate": {
"post": {
"x-amazon-apigateway-integration": {
"httpMethod": "POST",
"type": "aws_proxy",
"uri": {
"Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PostClickCollectStockUpdate.Arn}/invocations"
}
},
"responses": {}
}
}
},
"swagger": "2.0"
}
}
},
EDIT: This is what I have worked up to, but still API key required is not set to true in the API once the deployment has completed.
"ServerlessRestApi": {
"Type": "AWS::ApiGateway::RestApi",
"Properties": {
"Description":"InSite Web API Version 2.0.0.0",
"Body": {
"swagger": "2.0",
"info": {
"version": "1.0",
"title": {
"Ref": "AWS::StackName"
}
},
"x-amazon-apigateway-api-key-source" : "HEADER",
"schemes":["https"],
"paths": {
"tables/query/{tableid}": {
"get": {
"x-amazon-apigateway-integration": {
"httpMethod": "GET",
"type": "aws_proxy",
"uri": {
"Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${GetTableResponse.Arn}/invocations"
}
},
"responses": {},
"security": [
{
"api_key": []
}
]
}
},
"/products/update/": {
"post": {
"x-amazon-apigateway-integration": {
"httpMethod": "POST",
"type": "aws_proxy",
"uri": {
"Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PostClickCollectStockUpdate.Arn}/invocations"
}
},
"responses": {}
}
},
"/": {
"get": {
"x-amazon-apigateway-integration": {
"httpMethod": "GET",
"type": "aws_proxy",
"uri": {
"Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${Get.Arn}/invocations"
}
},
"responses": {}
}
},
"/tables/{tableid}/{columnid}": {
"get": {
"x-amazon-apigateway-integration": {
"httpMethod": "GET",
"type": "aws_proxy",
"uri": {
"Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${GetTableBasic.Arn}/invocations"
}
},
"responses": {}
}
}
},
"securityDefinitions": {
"api_key": {
"type": "apiKey",
"name": "x-api-key",
"in": "header"
}
}
}
}
},
So first off, if you are using the SAM framework, then why not try the serverless API (AWS::Serverless::Api) which has an Auth object where you can turn on ApiKeyRequired.
https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessapi
"ServerlessRestApi": {
"Type": "AWS::Serverless::Api",
"Properties": {
"Description":"InSite Web API Version 2.0.0.0",
"Auth": {
"ApiKeyRequired": "true"
},
"DefinitionBody": {
"swagger": "2.0",
"info": {
"version": "1.0",
"title": {
"Ref": "AWS::StackName"
}
},
"x-amazon-apigateway-api-key-source" : "HEADER",
"schemes":["https"],
"paths": {
"tables/query/{tableid}": {
"get": {
"x-amazon-apigateway-integration": {
"httpMethod": "GET",
"type": "aws_proxy",
"uri": {
"Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${GetTableResponse.Arn}/invocations"
}
},
"responses": {},
"security": [
{
"api_key": []
}
]
}
},
"/products/update/": {
"post": {
"x-amazon-apigateway-integration": {
"httpMethod": "POST",
"type": "aws_proxy",
"uri": {
"Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PostClickCollectStockUpdate.Arn}/invocations"
}
},
"responses": {}
}
},
"/": {
"get": {
"x-amazon-apigateway-integration": {
"httpMethod": "GET",
"type": "aws_proxy",
"uri": {
"Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${Get.Arn}/invocations"
}
},
"responses": {}
}
},
"/tables/{tableid}/{columnid}": {
"get": {
"x-amazon-apigateway-integration": {
"httpMethod": "GET",
"type": "aws_proxy",
"uri": {
"Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${GetTableBasic.Arn}/invocations"
}
},
"responses": {}
}
}
},
"securityDefinitions": {
"api_key": {
"type": "apiKey",
"name": "x-api-key",
"in": "header"
}
}
}
}
},
If for some reason you cannot use the serverless, you might be trying to overload the RestApi (which is fine, but you lose some of the other fine grain options). For full disclosure I do not work with API gateway in this way (I use the serverless transform) so this is all from reading the documentation and not from experiance.
I would try creating a bare bones AWS::ApiGateway::RestApi and then attach an AWS::ApiGateway::Method to the RestApi by reference it though RestApiId.
[1] https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-method.html
I think you are missing the "securityDefinitions":
Body:
swagger: "2.0"
...
...
securityDefinitions:
sigv4:
type: "apiKey"
name: "x-api-key"
in: "header"
x-amazon-apigateway-authorizer:
type: token
You can find here some more examples:
https://docs.aws.amazon.com/apigateway/latest/developerguide/api-as-s3-proxy-export-swagger-with-extensions.html
I'm currently writing swagger 3.0 documentation and using reDoc to render as nice UI for it. I have a few scenarios in my documentation where based on a previous properties enum I would want to display different schema object properties. Sadly I cant seam to figure out how to wire this together properly in my documentation. So far I have the following test endpoint:
{
"post": {
"operationId" : "test",
"summary": "test",
"description": "test",
"tags": [ "test" ],
"consumes": "application/json",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "./schemas/test1.json"
},
{
"$ref": "./schemas/test2.json"
}
],
"discriminator": {
"propertyName": "pet_type",
"mapping": {
"click": "./schemas/test1.json",
"open": "./schemas/test2.json"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success"
}
}
}
}
The test1.json looks like this:
{
"Cat": {
"type": "object",
"properties": {
"pet_type": {
"type": "string"
},
"hunts": {
"type": "boolean"
},
"age": {
"type": "integer"
}
},
"discriminator": {
"propertyName": "pet_type"
}
}
}
And the test2.json like this:
{
"Dog": {
"type": "object",
"properties": {
"pet_type": {
"type": "string"
},
"bark": {
"type": "boolean"
},
"breed": {
"type": "string",
"enum": [
"Dingo",
"Husky",
"Retriever",
"Shepherd"
]
}
},
"discriminator": {
"propertyName": "pet_type"
}
}
}
The desired out come would be to toggle between the two "test" jsons based on an enum (the drop down seen in the reDoc sample). What am I missing to get this result?
You can see an example of the discriminator result here under the feature section (the first gif)
After more digging I was able to figure out the issue... my structure for the most part.
On my index.json file I updated my components section to point at my components folder containing the schema as such:
"components": {
"$ref": "./components/test.json"
},
The test.json looks like the following:
{
"schemas": {
"Refinance": {
"description": "A representation of a cat",
"allOf": [
{
"$ref": "#/schemas/Pet"
},
{
"type": "object",
"properties": {
"huntingSkill": {
"type": "string",
"description": "The measured skill for hunting",
"default": "lazy",
"enum": [
"clueless",
"lazy",
"adventurous",
"aggressive"
]
}
},
"required": [
"huntingSkill"
]
}
]
},
"Purchase": {
"description": "A representation of a dog",
"allOf": [
{
"$ref": "#/schemas/Pet"
},
{
"type": "object",
"properties": {
"packSize": {
"type": "integer",
"format": "int32",
"description": "The size of the pack the dog is from",
"default": 1,
"minimum": 1
},
"foobar": {
"type": "string",
"description": "some ol bullshit"
}
},
"required": [
"packSize"
]
}
]
},
"Pet": {
"type": "object",
"discriminator": {
"propertyName": "petType"
},
"properties": {
"petType": {
"description": "Type of a pet",
"type": "string"
}
},
"xml": {
"name": "Pet"
}
}
}
}
And finally the schema for the endpoint gets referenced as follows:
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "../../index.json#/components/schemas/Pet"
}
}
}
},
We are using swagger 2.0 to document our .Net Web API's which we are hosting in Azure behind Azure API Management. I am having troubles getting the documentation to detail the complex objects that are being posted as part of the body. Azure shows no details about the object at all leaving me to have to document them myself. Below is the json file that I imported into Azure API Management.
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Hotel Search",
"description": "The seodecnvewjkl"
},
"basePath": "/v1",
"consumes": [
"application/xml",
"application/json"
],
"produces": [
"application/xml",
"application/json"
],
"schemes": [
"http",
"https"
],
"paths": {
"/hotels/search": {
"post": {
"operationId": "searchCommand",
"description": "Searches for hotels",
"parameters": [
{
"name": "hotelSearchRq",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/HotelSearchRq"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"title": "HotelSearchRs",
"$ref": "#/definitions/HotelSearchRs"
}
},
"400": {
"description": "Bad Request"
},
"404": {
"description": "Unauthorised"
}
}
},
"get": {
"operationId": "searchQuery",
"parameters": [
{
"name": "CorrelationId",
"in": "query",
"type": "string"
}
],
"responses": {
"200": {
"description": "Successful response"
}
}
}
}
},
"definitions": {
"StayDetail": {
"type": "object",
"properties": {
"NumberOfGuests": {
"type": "integer"
},
"CheckinDate": {
"type": "string",
"format": "date",
"description": "the date that the stay starts from"
}
}
},
"HotelSearchCriteria": {
"type": "object",
"properties": {
"MaximumResults": {
"type": "integer",
"format": "int64"
},
"StayDetails": {
"$ref": "#/definitions/StayDetail"
}
}
},
"HotelSearchRq": {
"type": "object",
"properties": {
"CustomerTransactionIdentifier": {
"type": "string",
"description": "The customers transaction identifier"
},
"search_criteria": {
"$ref": "#/definitions/HotelSearchCriteria"
}
}
},
"HotelSearchRs": {
"type": "object"
}
}
}
Azure Api Management operation screen
Can someone please help me with how I can get the body documented automatically from the swagger documentation?
Currently the request and response body information from a Swagger doc are not displayed in the developer portal documentation.
This is no longer the case. Samples and schema are displayed in the developer portal.