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.
Related
I am learning to use Swagger to document my API, and everything was well-explained until I got to the authentication portion. To give you some context of my API's authentication: it uses passport-jwt to authenticate users, sends an access token in the response body, and sets a refresh token in an httpOnly cookie. This is the swagger.json documentation I have so far:
{
"swagger": "2.0",
"info": {
"title": "API",
"description": "Coin-based API",
"version": "1.0.0"
},
"host": "localhost:4000",
"schemes": ["http"],
"consumes": ["application/json"],
"produces": ["application/json"],
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"in": "header",
"bearerFormat": "JWT"
}
}
},
"paths": {
"/api/users/transfer": {
"patch": {
"summary": "Transfer coins from one user to another",
"description": "Transfers coins from one user to another",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"type": "object",
"properties": {
"amount": {
"example": "any"
},
"recipient": {
"example": "any"
}
}
}
}
],
"responses": {
"200": {
"description": "Returns the user's new balance"
},
"400": {
"description": "Cannot transfer to yourself and/or Amount must be greater than 0"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Insufficient funds"
},
"404": {
"description": "User not found"
}
}
}
},
I couldn't find a good reference on what the best practices are to let the client know that he needs to send a access token in the header. Right now on my swagger Ui, I see a an open lock and no information about the authorization process. What should I do?
I expect the client to see the information about the authorization process and able to send a request with an access token.
I'm trying to pass the spec parameter in the url to the swagger editor to be able to open the API spec passed in the URL
https://editor.swagger.io/?spec={...}
as documented here:
https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
spec SPEC Object={}. A JavaScript object describing the OpenAPI definition. When used, the url parameter will not be parsed. This is useful for testing manually-generated definitions without hosting them.
but it seems that doesn't work, here the example
below the spec put in the link:
{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Swagger"
},
"paths": {
"/mypath": {
"get": {
"operationId": "listPets",
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "A paged array of pets"
}
}
}
}
}
}
I am new in swagger and want to deploy an API which is having query string. This is the API I am getting encoded URL after passing the parameter in the GET method.
API URL with Parameter should be:-
baseurl/v1/auth/getOTP?email=somename#email.com
but I am getting something like:-
baseurl/v1/auth/getOTP?email=somename%40email.com
what I have tried is:-
"/auth/getOTP": {
"get": {
"tags": [
"pet"
],
"summary": "",
"description": "",
"operationId": "findPetsByStatus",
"produces": [
"application/json",
"application/xml"
],
"parameters": [
{
"name": "email",
"in": "path",
"description": "",
"required": true,
"type": "string",
}
],
"responses": {
"200": {
"description": "successful operation",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Pet"
}
}
},
"400": {
"description": "Invalid value"
}
},
"security": [
{
"petstore_auth": [
"write:pets",
"read:pets"
]
}
]
}
},
Swagger OpenAPI has Specified: in this GitHub Issue-1840, It is specifically disallowed on in: path parameters for the same reason they don't allow optional path parameters, e.g. {/foo} By having variable path segments it become difficult to resolve a URL to an operation.
If you want to use some kind of hack then follow this GitHub Issue-230.
If you really needed then Its support in in: query parameters, as below,
The allowReserved keyword specifies whether the reserved characters :/?#[]#!$&'()*+,;= in parameter values are allowed to be sent as they are, or should be percent-encoded. By default, allowReserved is false, and reserved characters are percent-encoded.
Here you need to set it to true,
"parameters": [
{
"name": "email",
"in": "query",
"description": "",
"required": true,
"type": "string",
"allowReserved": true
}
],
Look at the Example Swagger Describing Parameters
and For more details follow Swagger Serialization.
I am using Swagger Editor to work on a JSON Swagger 2.0 API definition. I have reduced my definition to a minimum example of the problem I am experiencing. The problem occurs when I use a reference object to define a path parameter that is shared between multiple endpoints.
Example endpoints:
/my-api/{id}/some-thing
/my-api/{id}/some-other-thing
Since these id parameters are defined the same way, I abstracted them to the parameters section of the JSON file, and included them with "$ref": "#/parameters/testObjectId".
The Swagger reduced definition shows this:
{
"swagger": "2.0",
"info": {
"title": "Test Service",
"description": "REST API for TestObjects",
"version": "1.0.0"
},
"host": "api.not-a-real-url.com",
"schemes": [
"https"
],
"basePath": "/api/test-objects",
"produces": [
"application/hal+json"
],
"consumes": [
"application/json"
],
"paths": {
"/{id}": {
"get": {
"operationId": "getTestObject",
"summary": "Get a TestObject resource referenced by slug string ID",
"security": [],
"parameters": [
{
"$ref": "#/parameters/testObjectId"
}
],
"responses": {
"200": {
"description": "Success",
"schema": {
"type": "object",
"properties": {}
}
},
"default": {
"description": "Error",
"schema": {
"type": "object",
"properties": {}
}
}
}
}
}
},
"parameters": {
"testObjectId": {
"name": "id",
"in": "path",
"required": true,
"type": "string",
"format": "slug",
"description": "Immutable, unique identifier of a TestObject"
}
},
"definitions": {
}
}
But when this is rendered in Swagger, I get the following error:
Errors
Semantic error at paths./{id}
Declared path parameter "id" needs to be defined as a path parameter at either the path or operation level
The problem is that id is actually defined, only it appears that the check which throws this error is occurring before the $ref is included. The Swagger output looks correct.
Further, I have used this approach for about 6 months (as long as I have used Swagger) and I am just now running into the problem for the first time. Is there something I should be doing differently to prevent this error? Am I misusing Swagger by doing it this way?
Your spec is valid. It was a bug introduced in Swagger Editor v.3.2.2, it was fixed in v.3.2.3 (released on January 6, 2018).
After deploying AWS API Gateway via CLI (using put-rest-api and create-deployment) I want to do some testing of my API description in Postman.
After exporting the API via AWS Console (MyAPI - Stages - MyStage - Export - Postman) no body content is imported to Postman.
Does anyone know how to solve this?
When you export with postman extensions, the swagger file contains the definition of the model and the fact that its a parameter to POST, but postman does not show it in content. This is how postman import works. There is a feature request for this in gihub https://github.com/postmanlabs/postman-app-support/issues/1235
...
"/": {
"post": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "TestModel",
"required": true,
"schema": {
"$ref": "#/definitions/TestModel"
}
}
],
...
"definitions": {
"TestModel": {
"type": "object",
"properties": {
"photos": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"pages": {
"type": "string"
}
...
}
}
},
"title": "TestModel"
}
}
}