I'm trying to define a post endpoint using swagger, but it isn't allowing the requestBody parameter:
/names/{roster}:
get:
#...
post:
x-swagger-router-controller: names
description: Adds or removes name(s)
operationId: manageNames
parameters:
- name: roster
in: path
description: the roster to use
type: string
required: true
requestBody:
content:
'application/json':
schema:
$ref: '#/definitions/ManageNamesRequest'
when I run npm start, I get this:
API Errors:
#/paths/~1names~1{roster}/post: Additional properties not allowed: requestBody
1 error and 0 warnings
What's wrong with my spec?
You are probably mixing OpenAPI/Swagger 2.0 and OpenAPI 3.0 syntax. Your spec seems to be 2.0, but the requestBody keyword is a 3.0 feature. In 2.0, the request body is defined as a body parameter:
paths:
/names/{roster}:
post:
produces:
- application/json
...
parameters:
- ...
- in: body
name: body
required: true
schema:
$ref: '#/definitions/ManageNamesRequest'
More info: Describing Request Body
Related
I'm setting up a new server and my goal is to implement multipart/form-data in OpenApi3.0's yaml file. I encounter "should NOT have additional properties (consume)" error in Node.js and wanna know how to fix this error or how to implement multipart/form-data in OpenApi3.0's yaml file?
This is my OpenApi3.0's yaml file to implement this goal, it will report the error I mentioned above.
openapi: 3.0.1
info:
title: myapp
description: My cool app
version: 1.0.0
servers:
- url: /api/v1/user
tags:
- name: User
description: User Operations
paths:
/onboarding/signature:
post:
tags:
- User
description: Onboarding Upload Signature API - with parameters user's email and image file
requestBody:
description: Request Body {email, image}
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/onboardingSignature'
required: true
responses:
200:
description: OK
201:
description: Created
400:
description: Bad Request
500:
description: Internal Server Error
components:
schemas:
onboardingSignature:
description: Onboarding Signature File
type: object
properties:
email:
type: string
image:
format: binary
I expect the implementation of uploading file in Swagger use multipart/form-data format.
I use swaggerHub for write the documentation of my new app Node but I have a problem with one api.
My API require two params.
Example : POST http://cloud.amazingwebsite.com/:service/:action
Ok, if you want to use this API, you must to give two values. My problem is that the doc of swaggerHub propose only examples with one param.
Please, do you have a example with two params ? Is it possible ? Thanks
If you do it like this:
"/{service}/{action}":
x-swagger-router-controller: serviceController
post:
summary: To perform an action
operationId: serviceAction
parameters:
- name: service
in: path
required: true
type: string
description: Request Path Param for service
- name: action
in: path
required: true
type: string
description: Request Path Param for Action
responses:
'200':
description: Success
schema:
"$ref": "#/definitions/SuccessResponse"
default:
description: Error
schema:
"$ref": "#/definitions/ErrorResponse"
definitions:
SuccessResponse:
type: object
ErrorResponse:
required:
- error
properties:
error:
type: string
I'm using Swagger with NodeJS, and when I test an example I have this error.
Here is my YAML:
swagger: "2.0"
info:
version: "0.0.1"
title: Hello World App
# during dev, should point to your local machine
host: localhost:10010
# basePath prefixes all resource paths
basePath: /
#
schemes:
# tip: remove http to make production-grade
- http
- https
# format of bodies a client can send (Content-Type)
consumes:
- application/json
# format of the responses to the client (Accepts)
produces:
- application/json
paths:
/movie:
# our controller name
x-swagger-router-controller: movie
get:
description: get the movies list
# define the type of response for Success "200" and Error
responses:
"200":
description: Success
schema:
$ref: "#/definitions/GetMoviesListResponse"
default:
description: Error
schema:
$ref: "#/definitions/ErrorResponse"
/swagger:
x-swagger-pipe: swagger_raw
# complex objects have schema definitions
definitions:
GetMoviesListResponse:
required:
- movies
properties:
# The array of movies
movies:
type: array
items:
type: object
properties:
id:
type: string
title:
type: string
year:
type: number
ErrorResponse:
required:
- message
properties:
message:
type: string
Given your YAML, and assuming you're using swagger-tools with the options given in their tutorials, x-swagger-router-controller: movie will route any requests to GET /movie to a function called get exported from the module /controllers/movie.js in your project. Have you set that up?
Also check your swagger options to check that the correct controllers path is included, e.g. controllers: `${__dirname}`/controllers.
Using node v7.10.0 and npm 4.2.0.
I have created a nodejs 'Hello World' project and I was trying to reorganize the swagger.yaml taking the paths out of the main yaml file into a sepparate paths.yaml file:
This is my api/swagger/swagger.yaml:
swagger: "2.0"
info:
version: "0.0.1"
title: Hello World App
# during dev, should point to your local machine
host: localhost:10010
# basePath prefixes all resource paths
basePath: /
#
schemes:
# tip: remove http to make production-grade
- http
- https
# format of bodies a client can send (Content-Type)
consumes:
- application/json
# format of the responses to the client (Accepts)
produces:
- application/json
paths:
$ref: './paths.yaml'
/swagger:
x-swagger-pipe: swagger_raw
# complex objects have schema definitions
definitions:
HelloWorldResponse:
required:
- message
properties:
message:
type: string
ErrorResponse:
required:
- message
properties:
message:
type: string
and this is the api/swagger/paths.yaml that I'm referencing to:
/hello:
# binds a127 app logic to a route
x-swagger-router-controller: hello_world
get:
description: Returns 'Hello' to the caller
# used as the method name of the controller
operationId: hello
parameters:
- name: name
in: query
description: The name of the person to whom to say hello
required: false
type: string
responses:
"200":
description: Success
schema:
# a pointer to a definition
$ref: "#/definitions/HelloWorldResponse"
# responses may fall through to errors
default:
description: Error
schema:
$ref: "#/definitions/ErrorResponse"
I get the following Swagger error:
Relative paths to the individual endpoints. They must be relative to the 'basePath'.
Reference could not be resolved: ./paths.yaml
Both files 'swagger.yaml' and 'paths.yaml' are placed in the same directory 'api/swagger/'.
I've tried to reference paths.yaml in different ways:
paths:
$ref: 'paths.yaml'
or
paths:
$ref: './api/swagger/paths.yaml'
But I get the same error. Is it possible to reference the paths in a sepparate yaml file?
I have a swagger yaml specification like this :
swagger: "2.0"
info:
version: "0.0.1"
title: Chat API
# during dev, should point to your local machine
host: localhost:5000
# basePath prefixes all resource paths
basePath: /api/v2
#
schemes:
# tip: remove http to make production-grade
- http
- https
# format of bodies a client can send (Content-Type)
consumes:
- application/json
# format of the responses to the client (Accepts)
produces:
- application/json
paths:
/room:
post:
summary: Get room
operationId: getRoom
tags:
- room
parameters:
-
name: token
in: header
description: "token to be passed as a header"
default: "ZjE4YjMxNmY3OGEzNDMyN2JiYjJmYTQwMDBjODg4OWM="
required: true
-
name: room_id
in: body
description: "get room"
required: true
schema:
$ref: "#/definitions/Room"
definitions:
Room:
required:
- room_id
properties:
room_id:
type: string
This yaml file is compiled well without the header part. If I include the header in the paramerts . The nodejs app keep throwing : "Swagger validation errors"
-
name: token
in: header
description: "token to be passed as a header"
default: "ZjE4YjMxNmY3OGEzNDMyN2JiYjJmYTQwMDBjODg4OWM="
required: true
I don't know what was wrong in this part. I want to add the header to this spec file.
You simply need to add the type attribute. Swagger doesn't know if this is a string, an integer, etc. (although one could say the default explains it).
- name: token
in: header
description: "token to be passed as a header"
default: "ZjE4YjMxNmY3OGEzNDMyN2JiYjJmYTQwMDBjODg4OWM="
required: true
type: string