So I'm fairly new to creating API documentation and I'm having some difficulty creating a new entry via the swagger UI. I keep getting a 405 response. I have no idea what the issue is, I've become code blind. The link to the API is below. Any pointers would be greatly appreciated.
https://swaggerhub.com/apis/Sharper-Web-Dev/test/1.0.0
Your definition specifies SwaggerHub's mock server (virtserver.swaggerhub.com) as the target server. The mock server generates the responses based on the responses defined in your API definition. POST /charity defines just the 405 response, that's why the mock returns 405.
To get a "normal" response, you need to define a 200 OK or 201 Created response, and add the response schema (or response examples) describing the desired JSON structure.
paths:
/charity:
post:
...
produces:
- application/json
parameters:
...
responses:
200:
description: OK
schema:
$ref: "#/definitions/MyResponseSchema"
405:
description: "Invalid input"
See How Response Mocking Works in SwaggerHub docs for further information.
Related
I want to make an API negative test scenario with Rest-Assured Library. I'm creating a get request for a data that doesn't exist. When I print this response to the console, I want to see the text 'not found' Because postman says this is the request body. But my test failed on get method. I am getting that error
io.restassured.internal.http.HttpResponseException: status code: 404, reason phrase: Not Found
Actually I know the status code is 404. But I can not test about it. How can i write that negative scenario
Response response = given().
when().
get("https://restful-booker.herokuapp.com/booking/1001");
I am using OpenAPI (Swagger) to define a web service.
In the response section, I define the following code explicitly
responses:
'200':
description: Your order has been placed
content: ...
However, when I call the service, it returns "200 OK", which is a standard http status code description instead of the description I define explicitly
According to here https://swagger.io/docs/specification/describing-responses/, it says "If a response range is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code."
Do I miss/misunderstand something?
The description field in the OpenAPI definition is metadata used for documentation purposes only.
This description is not related to the status text (aka reason-phrase) value in HTTP responses, such as "OK" in "HTTP/1.1 200 OK". Most servers/frameworks use common status text e.g. "200 OK" or "403 Forbidden".
I am facing fellow two problems related to Swagger open API
I am not able to pass custom header through swagger open API while calling my API, please suggest how can we pass custom header, through swagger open API.
When I added POI dependency on my project's pom.xml, it stopped working through swagger open API, however, it is working with the postman, please suggest what could be the issue.
From Describing Parameters:
An API call may require that custom headers be sent with an HTTP request. OpenAPI lets you define custom request headers as in: header parameters. For example, suppose, a call to GET /ping requires the X-Request-ID header:
GET /ping HTTP/1.1
Host: example.com
X-Request-ID: 77e1c83b-7bb0-437b-bc50-a7a58e5660ac
Using OpenAPI 3.0, you would define this operation as follows:
paths:
/ping:
get:
summary: Checks if the server is alive
parameters:
- in: header
name: X-Request-ID
schema:
type: string
format: uuid
required: true
My API consumes requests only with Header - Content-type:application/json object.
To do the same I use:
#OA\RequestBody(
description= "Provide company search parameter",
required= true,
#OA\JsonContent(
type="object",
#OA\Property(property="company_name", type="string")
)
)
But for some requests I don't need the RequestBody, only hit the resource and get data. How do I do it without RequestBody?
P.S. This request requires a GET method (POST can be used, if that helps) but GET doesn't accept a RequestBody.
This case cannot be described by OAS 3.0, and the restriction on GET requestBodies is to avoid attempting to describe API behaviour which the HTTP spec says is undefined. The restriction on specifying Content-Type as a 'manually' defined header is also to ensure there is no ambiguity as to which mechanism is supposed to set this header.
https://github.com/OAI/OpenAPI-Specification/issues/1628
When a client is sending the Content-Type header, it is used to describe the body of the request (not the response)
To influence the the response type a client can send an Accept header.
For example: Accept: application/json
I have an API call which responds 200 OK and returns an HTML. I would like to add this to my API documentation
(especially since i validate it using dredd and unless i provide it with the expected response body the test fails). How
would i do this in Swagger?
--- More details ---
My Response to an API call is 200 OK and with a one line Response Body:
<html><body>You are being redirected.</body></html>
I can easily define the Response Body in Blueprint in the following form:
+ Response 302 (text/html; charset=utf-8)
+ Body
`<html><body>You are being redirected.</body></html>`
But i'm not sure how to do this in Swagger. Almost all examples i can find are for application/json responses (understandably) and i'm having trouble
guessing the correct syntax for this kind of response.
The relevant swagger text in my document is this (so far without specifying the response body, so with an empty body dredd
fails because the response body should be <html><body>You are being redirected.</body></html>):
# this is my API spec in YAML
swagger: '2.0'
info:
title: My API (Swagger)
description: blablabla
version: "1.0.0"
# the domain of the service
host: my.domain.com
# array of all schemes that your API supports
schemes:
- https
# will be prefixed to all paths
basePath: /
produces:
- application/json; charset=utf-8
paths:
/users/password:
post:
summary: Password Reset
description: |
Handles Reset password for existing user.
consumes:
- application/x-www-form-urlencoded
produces:
- text/html; charset=utf-8
parameters:
- name: "user[email]"
description: email
in: formData
required: true
type: string
default: "user#gmail.com"
tags:
- Reset Password
responses:
200:
description: Success
Please comment if you have any suggestions on this. Thanks!
Figured it out. the response object has a field called "examples" which allows to show examples to your API response.
The syntax is clearly shown in the specification and basically says you need to identify the MIME-type for the example response, in my case text/html and the value is the actual text.
so like this:
responses:
200:
description: success and returns some html text
examples:
text/html:
<html><body>Your HTML text</body></html>
That's it. Now whether or not dredd knows to take this value and compare it is another story. their docs state that any response other than JSON is validated as plain text so this should work.
Hope this helped.
In case someone needs this in the openapi version 3.0 you can do it this way:
Save your HTML. For example give this at the end of your file:
components:
schemas:
error401:
type: string
example: '<html>HTML text</html>'
Then you can reference this scheme in responses wherever you want. For example:
responses:
'401':
description: Error
content:
text/html:
schema:
$ref: '#/components/schemas/error401'