i am getting the issue in the swagger yaml format.
help me out to fix the below issue please.
Issue on Console:
Additional properties not allowed: x=swagger=router-controller in swagger config at: >paths//readinesstest/<
path:
/readinesstest/:
x=swagger=router-controller: readinesstest/readinesstest
get:
tags: [readinesstest]
operationId: prepareReadinessTest
description: Prepating test based on the user status
produces: [application/json]
responses:
'200':
description: user readiness test insert
schema: {$ref: '#/definitions/readinesstest'}
'400':
description: error
parameters:
- {$ref: '#/parameters/Bearer'}
/user/:
x-swagger-router-controller: users/users
get:
tags: [Users]
operationId: getUser
description: Gets the user
produces: [application/json]
responses:
'200':
description: User details returned
schema: {$ref: '#/definitions/userInfo'}
parameters:
- {$ref: '#/parameters/Bearer'}
Replace x=swagger=router-controller with x-swagger-router-controller. Note the - characters instead of =.
Related
I'm learning to use swagger and am having trouble finding the answer to this.
Let's say for example I have 10 endpoints that all share a group of responses, for example's sake let's say they are:
components:
responses:
'success':
description: Success
'failed':
description: Failed
'unknown':
description: Unknown
'dontincludeme':
description: A status I don't always want to include
Currently, as I understand it I need to reference them as follows in various paths:
paths:
/start:
post:
summary: Start a process
tags:
- Process Management
responses:
'1':
$ref: '#/components/responses/success'
'2':
$ref: '#/components/responses/failed'
'3':
$ref: '#/components/responses/unknown'
I'm looking for a way to 'group' them so that I can reference for example, 10 different responses at a time for a path. Is this possible? I know I can reference all the responses, but I don't always want to reuse all defined codes for all paths.
You can group different responses for the same response HTTP status code as in the example from the OAS3 documentation:
https://swagger.io/docs/specification/describing-responses/
But I don't think there is a template to paste a collection of responses with different status codes.
responses:
'200':
description: A JSON object containing pet information
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Hamster'
You could go one further and define a component that contains 'oneOf' those schemas - but you may start to lose legibility.
Another feature you could consider is the default response described in the same document.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/User'
# Definition of all error statuses
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
This will work well if many of the error responses use the same schema.
Note that this no longer documents the specific error codes that may be returned by the server - but still gives the client the opportunity to write a generic error handler.
You can use the default responses in components element.
In this example, 200 code is specific for each request. 4xx are common
paths:
"/api/account":
get:
...
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/user'
400:
$ref: '#/components/responses/BadRequest'
401:
$ref: '#/components/responses/Unauthorized'
403:
$ref: '#/components/responses/Forbidden'
...
components:
responses:
BadRequest:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Unauthorized
Forbidden:
description: Forbidden
NotFound:
description: The specified resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/error'
InternalError:
description: Internal error
For example I have 2 API operations:
GET v1/people/{id}
POST v1/people/{id}
Only one of these operations is shown in my Swagger UI API docs but I want both of them displayed. I have many examples where this is the case. In the Swagger documentation it states:
"Swagger defines a unique operation as a combination of a path and an HTTP method."
This would make me think what I want to do is possible as they are uniquely identified by the HTTP method.
If I change the path parameter for one in my swagger.yaml file they will both show.
eg:
GET v1/people/{personid}
POST v1/people/{id}
But I would rather keep them all standard otherwise my API docs will appear messy.
I am using swagger-ui-express 4.1.4.
/v1/people/{id}:
get:
summary: Get people.
security:
- cookieAuth: []
tags:
- People
parameters:
- in: path
name: id
required: true
schema:
type : integer
example: 123
responses:
'200':
description: OK
/v1/people/{id}:
post:
summary: Get people.
security:
- cookieAuth: []
tags:
- People
parameters:
- in: path
name: id
required: true
schema:
type : integer
example: 123
responses:
'200':
description: OK
Thanks for your help.
You can try same path with different method: https://swagger.io/docs/specification/paths-and-operations/.
paths:
/users/{id}:
summary: Represents a user
description: >
This resource represents an individual user in the system.
Each user is identified by a numeric `id`.
get:
...
patch:
...
delete:
...
In your example:
/v1/people/{id}:
get:
summary: Get people.
security:
- cookieAuth: []
tags:
- People
parameters:
- in: path
name: id
required: true
schema:
type : integer
example: 123
responses:
'200':
description: OK
post:
summary: Get people.
security:
- cookieAuth: []
tags:
- People
parameters:
- in: path
name: id
required: true
schema:
type : integer
example: 123
responses:
'200':
description: OK
I'm trying to build an API using OpenApi 3.0.2 for active documentation. I've managed to build a validated spec-file, and if I take out all of the OpenApi "stuff" from the API itself, all of the routes work properly, and I have no errors (unless I've managed to change something vital while attempting to solve this problem).
Additionally, my controllers do in fact have the generic controller names that this error suggests I use, so my initial thought was that it's having trouble finding my controllers. However, when I used Swagger 2.0 (before rebuilding it with 3.0), I didn't have this problem.
All of my controllers are structured similarly, and when I changed the order of the controllers (path '/users' first), I retrieved the same error ('users' swapped out for 'garments' in the error log).
That said, I feel that there must be something I'm doing wrong in my "bringing together" of the functioning API and the valid spec-file.
I've been looking for a solution to this problem for a while now, but I have found nothing. If this question has been asked and answered before, I apologize; please redirect me. This is my first StackOverflow question, so please be gentle. If I have missed any information important to the question, please let me know.
Error:
outfittr | 2019-01-21T13:51:37.150Z info: Valid specification file
outfittr | 2019-01-21T13:51:37.162Z info: Specification file dereferenced
outfittr | 2019-01-21T13:51:37.210Z info: No localhost or relative server found in spec file, added for testing in Swagger UI
outfittr | 2019-01-21T13:51:37.210Z debug: Register: GET - /garments
outfittr | 2019-01-21T13:51:37.211Z debug: GET - /garments
outfittr | 2019-01-21T13:51:37.212Z debug: Spec-file does not have router property -> try generic controller name: garmentsController
outfittr | 2019-01-21T13:51:37.212Z debug: Controller with generic controller name wasn't found either -> try Default one
outfittr | 2019-01-21T13:51:37.212Z error: There is no controller for GET - /garments
outfittr exited with code 0
openapi.yaml:
openapi: 3.0.2
info:
version: "1.0.0"
title: Outfittr API
paths:
/swagger:
x-swagger-pipe: swagger_raw
####################################### Garments ##############################################
/garments:
x-router-controller: garmentsController
get:
description: Returns an array of garments.
operationId: indexGarments
responses:
"200":
$ref: '#/components/schemas/Garment'
default:
$ref: "#/components/schemas/ErrorResponse"
post:
summary: Creates a new garment
operationId: newGarment
description: Adds garment to the system
responses:
'200':
$ref: '#/components/schemas/Garment'
default:
$ref: "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Garment'
description: User that was created.
/garments/{_id}:
x-router-controller: garmentsController
get:
description: Returns one garment
operationId: viewGarment
parameters:
- in: path
name: _id
schema:
type: string
required: true
description: Numeric ID of the user to get
responses:
"200":
$ref: '#/components/schemas/Garment'
default:
$ref: "#/components/schemas/ErrorResponse"
######################################## Users ################################################
/users:
x-router-controller: usersController
get:
description: Returns an array of users.
operationId: indexUsers
responses:
"200":
$ref: '#/components/schemas/User'
default:
$ref: "#/components/schemas/ErrorResponse"
post:
summary: Creates a new user
operationId: newUser
description: Adds user to the system
responses:
'200':
$ref: '#/components/schemas/User'
default:
$ref: "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/User'
description: User that was created.
/users/{_id}:
x-router-controller: usersController
get:
description: Returns one user
operationId: viewUser
parameters:
- in: path
name: _id
schema:
type: string
required: true
description: Numeric ID of the user to get
responses:
"200":
$ref: '#/components/schemas/User'
default:
$ref: "#/components/schemas/ErrorResponse"
####################################### Wardrobe ##############################################
/wardrobe:
x-router-controller: wardrobeController
get:
description: Returns an array of garments in the user's wardrobe.
operationId: indexWardrobeItems
responses:
"200":
$ref: '#/components/schemas/WardrobeItem'
default:
$ref: "#/components/schemas/ErrorResponse"
post:
summary: Creates a new wardrobe item
operationId: newWardrobeItem
description: Adds garment to the user's wardrobe in the system
responses:
'200':
$ref: '#/components/schemas/WardrobeItem'
default:
$ref: "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WardrobeItem'
description: User that was created.
/wardrobeItem/{_id}:
x-router-controller: wardrobeController
get:
description: Returns one wardrobe item
operationId: viewWardrobeItem
parameters:
- in: path
name: _id
schema:
type: string
required: true
description: Numeric ID of the user to get
responses:
"200":
$ref: '#/components/schemas/WardrobeItem'
default:
$ref: "#/components/schemas/ErrorResponse"
###################################### Components #############################################
servers:
- url: outfittr.net
- url: localhost:3000
components:
schemas:
User:
type: object
required:
- _id
- email
- username
- password
properties:
_id:
type: string
description: unique ID given by Mongo.
firstName:
type: string
description: First name of the user.
lastName:
type: string
description: Last name of the user.
email:
type: string
description: User's email address.
username:
type: string
description: User's username (for login)
password:
type: string
description: User's password (for login).
create_date:
type: string
description: date that the user joined.
__v:
type: integer
description: I have no idea.
Garment:
type: object
required:
- _id
- type
- imageLink
properties:
_id:
type: string
description: unique ID given by Mongo.
type:
type: string
description: type of garment
imageLink:
type: string
description: primary color of garment
__v:
type: integer
description: I have no idea.
WardrobeItem:
type: object
required:
- _id
- owner_id
- garment_id
properties:
_id:
type: string
description: unique ID given by Mongo.
unavailable:
type: boolean
description: Is the wardrobe item dirty, loaned out, or otherwise unavailable?
owner_id:
type: string
description: foreign key linking this wardrobe item to its owner.
garment_id:
type: string
description: foreign key linking this wadrobe item to the garment it is.
torn:
type: boolean
description: Is the wardrobe item torn?
reserveDate:
type: string
description: Optional - a date for which this wardrobe item must be worn
reserveTilDate:
type: string
description: Optional - a date after which the wardrobe item cannot be worn until the reserveDate.
__v:
type: integer
description: I have no idea.
ErrorResponse:
required:
- message
properties:
message:
type: string
Any help is vastly appreciated.
I'll answer this even if it's late because I have had this same problem and looked for a long time the solution. If someone else happens to have any reference on how to fix it.
When you set the controllers parameter in oas-tools:
OasTools.configure({
controllers: `${__dirname}/controllers`,
...
});
The default mapping that oas-tools makes to load the files is endpoint+Controller.js, in your case oas-tools would look for the export function indexGarments in .../controllers/garmentsController.js
Another example would be for the case /garments/{_ id}, the name of the controller file should be garments_idController.js
Using x-router-controller
If you want to use the parameter x-router-controller you have to put it inside the method:
...
/garments:
get:
x-router-controller: garmentsController
operationId: indexGarments
description: Returns an array of garments.
responses:
But be careful because it also modifies the value of the parameter (I do not know if this is a bug or because the name of the files has that requirement), for example, if you configure x-router-controller with the value garments.resource the file to be searched will be .../controllers/garmentsresource.js
In case you set the x-router-controller parameter and the file is not found, this error will be thrown:
info: Valid specification file
info: Specification file dereferenced
debug: Register: GET - /health
debug: GET - /health
debug: OAS-doc has x-router-controller property
error: undefined
For OAS3 you may try this:
paths:
/users:
get:
tags:
- User
x-openapi-router-controller: usersController
description: Returns an array of users.
operationId: indexUsers
responses:
"200":
$ref: '#/components/schemas/User'
can swagger docs be automated instead of typing it manually ? does anyone know some tools ? or libraries? . based from the sample below , instead og typing those manually is there a tool that can auto generate it based on models? , and it loopback can do it? or anyone know some tools? . and does it true loopback supports swagger docs generation. Thank You.
swagger: '2.0'
info:
version: 1.0.0
title: customcat
basePath: /api
host: 127.0.0.1:3333
consumes:
- application/json
- application/x-www-form-urlencoded
- application/xml
- text/xml
produces:
- application/json
- application/xml
- text/xml
- application/javascript
- text/javascript
paths:
/notes:
post:
tags:
- note
summary: Create a new instance of the model and persist it into the data source.
operationId: note.create
parameters:
- name: data
in: body
description: Model instance data
required: false
schema:
$ref: '#/definitions/note'
responses:
'200':
description: Request was successful
schema:
$ref: '#/definitions/note'
deprecated: false
put:
tags:
- note
summary: >-
Update an existing model instance or insert a new one into the data
source.
operationId: note.upsert
parameters:
- name: data
in: body
description: Model instance data
required: false
schema:
$ref: '#/definitions/note'
responses:
'200':
description: Request was successful
schema:
$ref: '#/definitions/note'
deprecated: false
get:
tags:
- note
summary: Find all instances of the model matched by filter from the data source.
operationId: note.find
parameters:
- name: filter
in: query
description: 'Filter defining fields, where, include, order, offset, and limit'
required: false
type: string
format: JSON
responses:
'200':
description: Request was successful
schema:
type: array
items:
$ref: '#/definitions/note'
deprecated: false
There is an online visual API builder, try: https://apibldr.com.
It will give you a visual way of building it, without writing the code.
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