I' writing the docs for web API with swagger, OpenAPI version 3. I use swagger php package to generate documented json from annotations. I have service, where I send post request to add new user, and requested body is json(so parameters are sent as json object). it has 2 parameters - email and password. request body looks like
{
"email": "test@test.com",
"password": "test"
}
here's YAML of swagger
paths:
/users:
post:
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SignUp'
responses:
'200':
description: successful operation
here's reference schema which contains request parameters ( /components/schemas/SignUp
)
SignUp:
title: SignUp
description: Adds new user
type:object
required:
- email
- password
properties:
email:
description: User's email
type: string
maximum: 255
pattern: email
password:
description: User's password
type: string
maximum: 255
here's how it looks in swagger UI as you can see on image, requested body is empty(while I have 2 parameters) and this is the issue. if I change the header from application/json
to application/x-www-form-urlencoded
then it will work(it will show all parameters in parameters list). how to make it show json object parameters in that list?
Your spec is correct and the displayed result in Swagger UI is correct and exactly as expected for OpenAPI 3.0 definitions.
Note there are two sections, "Parameters" (for parameters
) and "Request body" (for requestBody
). In OpenAPI 3.0, parameters
is only used for query parameters, path parameters, request headers and cookies; whereas requestBody
is displayed in the "Request body" section. You can click "Model" link to view the request body schema with property descriptions.
The technical post webpages of this site follow the CC BY-SA 4.0 protocol. If you need to reprint, please indicate the site URL or the original address.Any question please contact:yoyou2525@163.com.