I am setting up our api documentation and i'm using swagger-spec and swagger ui.
I got everything working except that my CURL example adds our access_token twice
curl -X DELETE --header "Accept: application/json" "http://api host/api/user?filter%5Bid%5D%5BEQUAL%5D=1&access_token=Token_TOKANE&access_token=Token_TOKANE"
I renamed the api_key in swagger_ui index
var apiKeyAuth = new SwaggerClient.ApiKeyAuthorization("access_token", key, "query");
window.swaggerUi.api.clientAuthorizations.add("access_token", apiKeyAuth);
Screenshot
Swagger delete path
delete:
tags:
- User
summary: Delete user from you organization
operationId: deleteUser
description: Deletes a single by id. Gets id from filter param in query
parameters:
- name: filter[id][EQUAL]
in: query
type: integer
required: true
description: id to delete
responses:
200:
description: OK
schema:
$ref: '#/definitions/Message'
security:
- access_token: []
Security definition
securityDefinitions:
access_token:
type: string
in: query
name: access_token
The same issue can be seen in the swagger-ui live demo
If anyone knows of a fix or workaround i would appreciate it.
This has just been addressed in swagger-js. You can update your swagger-ui by building this locally and using npm link against the local build of swagger-ui. The release of swagger-ui with this fix is coming soon.
Related
I have the following POST method definded in OpenAPI:
post:
tags:
- Courses
description: Creates a new Course and add it to specified Program
parameters:
- name: Program
in: path
description: Specified Program to add the new course to
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Course'
In insomnia I can define the Course object, I want to add via the body/JSON tab, however how can I define the needed parameter? It doesn't work in the Query tab the same way it does for GET methods.
Do I manually set the path of the POST request with the parameter, or is there a build in way (or is it not possible at all)?
Here is the curl when trying to add the Program Parameter in the Query tab:
curl --request POST \
--url 'http://localhost:8080/Courses?Program=Testprogram' \
--header 'content-type: application/json' \
--data '{
"name": "TestCourse",
"type": "UE",
"etcs": 26,
"courseID": 909090
}'
I had the exact same issue and my problem was an internal redirect (nginx) from HTTP to HTTPs which changed the request type and made it impossible to maintain the body of the requests.
Oddly enough it worked with "Multipart Form".
So please make sure you provide your FULL URI in Insomnia, including the protocol to use for the request.
I found this issue by copying the request from the Insomnia GUI as a cURL command and pasting it into my terminal, which gave me an 301 Permanently moved. ;)
i am making openapi.yaml till now as well as deploying my test API's on the google cloud endpoints is working but now i made some changes i am sending parameter in body to the get api (e.g email) and getting some response but actually on the local it is working fine with postman after deploying openapi.yaml file it is not working on the google cloud endponits portal
So, anybody has any solution or answers for this so please help me
For safety i am also sharing error screenshot also y code snippet
"/api/getRecords":
get:
description: "Get All Records Details."
operationId: "getRecords"
produces:
- "application/json"
parameters:
- description: "Message to getRecords"
in: query
name: getRecords
type: object
required: false
schema:
$ref: "#/definitions/echoMessage"
responses:
200:
Also,
Try your code like this :
# [START swagger]
swagger: "2.0"
info:
description: "A simple Google Cloud Endpoints API example."
title: "Endpoints Example"
version: "1.0.0"
host: "abc.appspot.com"
# [END swagger]
parameters:
email:
name: email
in: query
type: string
required: true
Then use shorthand syntax in the path:
path:
"/api/getRecords":
get:
description: "Get All Records Details."
operationId: "getRecords"
parameters:
- $ref: "#/parameters/email"
responses:
200:
description: "Get records details"
schema:
$ref: "#/definitions/postMessage"
It will work.
I have yaml file:
openapi: 3.0.1
info:
title: My API
version: v1
paths:
# /users;id=3;id=4?metadata=true
/users:
get:
parameters:
- in: query
name: offset
schema:
type: integer
description: The number of items to skip before starting to collect the result set
- in: query
name: limit
schema:
type: integer
description: The numbers of items to return
- in: query
name: origin
style: form
explode: false
schema:
type: object
properties:
city:
type: string
zip:
type: string
responses:
'200':
description: A list of users
When I click "execute" in https://editor.swagger.io, the generated Curl looks like this:
curl -X GET "https://editor.swagger.io/users?offset=2&limit=12&origin=city,atlanta,zip,303" -H "accept: */*"
However, I need it to be like this:
curl -X GET "https://editor.swagger.io/users?offset=2&limit=12&origin=city:atlanta|zip:303" -H "accept: */*"
Is it possible to do this? I could not find any info in documentation about setting custom delimeters.
Short answer: No.
Your specific use case isn't covered by serialize parameters and they follow the rfc6570 - it's a good idea to follow the standard if you want to design a well accepted web api.
You specified explode: false and style:form.
When you turn explode:true on you will get this instead:
city=atlanta&zip=303
When you specify style:deepObject you will get:
origin[city]=atlanta&origin[zip]=303
The spaceDelimited and pipeDelimited style won't work with objects.
Working without schema
You can of cause work without a schema and define your origin query parameter of type string.
The documentation should explain exactly what you expect and a little example will help people to use your API.
I won't use that pattern for an open API, but this can be a workaround for an internal API.
I am attempting to create a custom connector for MS Flow\Logic Apps that uses some of the REST endpoints that are part of the microsoft graph but am having trouble in understanding how to document the API in OpenAPI 2.0 specification
The MS documentation
https://learn.microsoft.com/en-us/graph/api/group-post-owners?view=graph-rest-1.0#example
says to include
"#odata.id": "https://graph.microsoft.com/v1.0/users/{id}"
as a $ref parameter as part of the request body
but how do I document this in OpenAPI 2.0 specification?
This is what I have got so far...
'/groups/{team-id}/owners':
post:
tags:
- teams.team
summary: Add a new owner to the team
operationId: teams.AddOwner
consumes:
- application/json
parameters:
- name: team-id
in: path
required: true
type: string
description: Id of the MS team
x-ms-summary: Team Id
x-ms-visibility: important
- name: body
in: body
required: true
schema:
type: object
properties:
userId:
type: string
description: Id of the user to be added as an owner to the team
x-ms-summary: User Id
x-ms-visibility: important
'#odata.id':
default: https://graph.microsoft.com/v1.0/users/{userId}
responses:
'204':
description: Success
default:
$ref: '#/responses/error'
x-ms-docs-operation-type: operation
When I submit the above to create the custom connector I get the following error
Specified file does not match OpenAPI 2.0 specification: 'JSON is valid against no schemas from 'oneOf'. Path 'paths./groups/{team-id}/owners.post.parameters[1]'.'
EDIT
I have updated the OpenAPI to look like below
This means that I can import and use this... but I have to construct the URL for the #odata.id parameter manually in the workflow!
"#odata.id": "https://graph.microsoft.com/v1.0/users/{id}"
'/groups/{team-id}/owners/$ref':
post:
tags:
- teams.team
summary: Add a new owner to the team
operationId: teams.AddOwner
consumes:
- application/json
parameters:
- name: team-id
in: path
required: true
type: string
description: Id of the MS team
x-ms-summary: Team Id
x-ms-visibility: important
- name: body
in: body
required: true
schema:
type: object
properties:
'#odata.id':
title: User Id
type: string
x-ms-summary: User Id
x-ms-visibility: important
responses:
'204':
description: Success
default:
$ref: '#/responses/error'
x-ms-docs-operation-type: operation
EDIT
How should I be specifying this to get the userId?
How do I specify the body parameter correctly?
Is there any documentation\examples on how to do this?
Any help would be much appreciated
Thanks in advance
Pete
One of the easiest ways I’ve found to create a PowerApps Custom Connector is to:
Use Postman to craft a working request
Build the Custom Connector from Blank
Test in the Custom Connector “Test” area
Then, you can download the Swagger file if you need it. Basically, let PowerApps build the Swagger file FOR YOU instead of the other way around.
Here is a YouTube video of the method I like to use.
https://m.youtube.com/watch?v=-wQljWG35zM
I am starting a REST service, using Swagger Codegen. I need to have different responses for different parameters.
Example: <baseURL>/path can use ?filter1= or ?filter2=, and these parameters should produce different response messages.
I want my OpenAPI YAML file to document these two query params separately. Is this possible?
It is not supported in the 2.0 spec, and not in 3.0 either.
Here are the corresponding proposals in the OpenAPI Specification repository:
Accommodate legacy APIs by allowing query parameters in the path
Querystring in Path Specification
If you're still looking, I found out a way around this problem. It's a bit of a hack, but it works.
Basically, you can have two definitions to the same path by adding a slash (/) in the URL.
That way, you can set a response for <baseURL>/path with the ?filter1= parameter and set another response for <baseURL>//path with the ?filter2= parameter. It's also important that you give an unique operationId for each of the definitions.
paths:
/path/you/want:
get:
summary: Test
operationId: get1
parameters:
- name: filter1
type: string
in: path
required: true
responses:
200:
description: Successful response
schema:
$ref: '#/definitions/SomeResponse'
/path/you//want:
get:
summary: Another test
operationId: get2
parameters:
- name: filter2
type: string
in: path
required: true
responses:
200:
description: Successful response
schema:
$ref: '#/definitions/SomeOtherResponse'
I tried this with a path parameter and it worked just fine!
In swagger defining location,type explicitly is what defines these variables.
You have all the required fields to avoid collision of variables, for a json body you have to reference a declaration or use an example schema as shown below. For my case I have used a schema example rather than a declaration reference
/auth/account/password/reset/{userId}/{resetToken}:
post:
consumes:
- application/json
parameters:
- in: path
name: userId
type: string
required: true
- in: path
type: string
name: resetToken
required: true
- in: header
name: authorization
required: true
type: string
- in: body
name: body
required: true
schema:
type: object
example:
password: password
confirmPassword: password
responses:
"200":
description: OK
In Swagger you can add ? to make endpoints different.
i.e. /articles and /articles?:
When using ? in Swagger editor you will see error:
However on your final Swagger page there will be mark VALID
Additional information:
Remember about unique operationId for duplicated entries