Using swagger made the following api:
openapi: 3.0.0
servers: []
info:
description: This is a simple API
version: "1.0.0"
title: Simple API
paths:
/inventory:
get:
summary: searches inventory
description: |
By passing in the appropriate options, you can search for
available inventory in the system
parameters:
- in: query
name: searchString
description: pass an optional search string for looking up inventory
required: false
schema:
type: string
responses:
'200':
description: search results matching criteria
content:
application/json:
schema:
type: array
items:
type: string
description: "Item names"
'400':
description: bad input parameter
content:
application/json:
schema:
type: object
properties:
'/inventory':
type: boolean
message:
type: string
/baka:
get:
responses:
400:
description: "ERROR"
content:
application/json:
schema:
type: object
properties:
'/baka':
type: boolean
message:
type: string
As you can see I use the following pattern for my error responses:
endpoint_name: boolean
message: string
So how I can create a common response object that swagger will auto-populate with endpoint name?
Related
I'm building a very simple API with maven plugin configuration here. But it generates some Authentication classes (auth package and some other classes like StringUtil, JSON) I've never defined in my configuration. I don't want all these classes, where do they come from ? :
Here is my student.yaml input file :
openapi: 3.0.0
info:
title: student API
description: student demo API by Anthony Errera
version: 1.0.0
paths:
/student:
description: Student Resource
get:
description: operation to fetch student
parameters:
- in: query
name: studentname
required: true
schema:
type: string
responses:
200:
description: Success response
content:
application/json:
schema:
type: array
items:
properties:
StudentID:
type: integer
example: 3
StudentName:
type: string
example: toto
post:
description: add a student
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/student'
responses:
201:
description: student created
components:
schemas:
student:
type: object
properties:
StudentID:
type: integer
example: 3
StudentName:
type: string
example: toto
I am using swagger with Open API 3.0.0
Following is my Api definition:
paths:
/offerers:
get:
summary: give all offerers back
operationId: allOfferers
description: give you all offerers back
responses:
'200':
description: oferers results
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/OfferersId'
links:
GetSingleOffererById:
$ref: '#/components/links/GetSingleOffererById'
'400':
description: something went terribly wrong
/offerers/{offererId}:
parameters:
- in: path
name: offererId
schema:
$ref: '#/components/schemas/OfferersId'
required: true
get:
parameters:
- $ref: '#/components/schemas/OfferersId'
summary: give one specified offerer back
operationId: singleOfferer
description: give one offerer back. Specified by its id
responses:
'200':
description: offerers results
content:
application/json:
schema:
$ref: '#/components/schemas/Offerers'
'400':
description: something went terribly wrong
components:
schemas:
OfferersId:
type: number
example: 123
Offerers:
type: object
required:
- offererId
- name
properties:
id:
$ref: '#/components/schemas/OfferersId'
name:
type: string
example: "Mark Mustermann"
location:
type: string
example: "90449 Nürnberg"
experience:
type: string
example: "8 Jahre"
openingHours:
type: string
example: "Werktags: 10:15-18:30/tWochenende: geschlossen."
links:
GetSingleOffererById:
operationId: singleOfferer
description: the offererId in the response will be used as offererId in the request
paramters:
offererId: $reponse.body#/OfferersId
Most of this Definition is error free. But the last section components/links gives me an error at line "operationId: singleOfferer":
should NOT have additional properties additionalProperty: operationId,
paramters
So my question:
How do I have to correct my definition, so that the reusable link is valid?
"should NOT have additional properties" error in the Swagger Editor usually means one of the following:
a keyword is misspelt,
syntax/structure is incorrect.
In your example it's (1) - paraMTers should be paraMETers.
I am trying to generate the API documentation using swagger editor. I specified my API specification as follow
paths:
/opendata/v1/{index}:
get:
tags: [verification]
description: Verify the person information
parameters:
- name: index
in: path
description: specific data index
required: true
type: string
- name: name
in: query
description: name of a person
required: false
type: string
- name: company name
in: query
description: name of a company
required: false
type: string
responses:
'200':
description: Success
content:
application/json:
schemas:
$ref: '#/responses/200'
responses:
'200':
description: Success
schema:
type: object
properties:
verification:
type: string
But its always showing error in the editor that "Not a valid response definition". I checked the specification for response from here. What changes I should do so that error will not come.
Note: I want the response in the json form like below:
{
verification:string
}
You are mixing OpenAPI/Swagger 2.0 and OpenAPI 3.0 syntax. Your spec seems to be swagger: '2.0', so you should use:
paths:
/opendata/v1/{index}:
get:
...
produces:
- application/json
responses:
200:
$ref: '#/responses/200'
Here's a related OpenAPI/Swagger 2.0 guide: Describing Responses
I'm trying to figure out this swagger API inheritance stuff by using allOf. This is my swagger yaml file.
swagger: '2.0'
info:
title: Test API
version: '1'
basePath: /api/v1
schemes:
- https
produces:
- application/json
paths:
/users:
get:
summary: Collection of users
tags:
- users
responses:
200:
description: A list of Users
schema:
$ref: "#/definitions/Users"
500:
$ref: "#/responses/BadRequest"
definitions:
User:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
Users:
type: array
items:
$ref: "#/definitions/User"
responses:
NonSuccess:
description: Generic response for all non-success responses
schema:
type: object
required:
- code
- message
properties:
code:
type: integer
description: The success code, 0 or -1.
message:
type: string
description: The description message for this success code
errors:
type: array
description: A map of errors within the request. Keyed by the parameter name and the values are the error details
BadRequest:
description: Invalid request parameters
allOf:
- $ref: "#/responses/NonSuccess"
When I paste this into the online editor, I get the following errors that I'm having a real hard time trying to figure out.
✖ Swagger Error
Additional properties not allowed: allOf
Jump to line 60
✖ Swagger Error
Not a valid response definition
Jump to line 22
The main problem seems to be Additional properties not allowed: allOf and I'm can't seem to figure out what I'm doing wrong in this case. I was trying to declare a basic non-success response so that all non-200 responses will inherit so that the API will have a very standard looking non-success response. I was under the impression I could do this with allOf and then add or overwrite the fields from that response. What exactly am I doing wrong?
The allOf tag can only be used on Schema objects. You can definitely use it on the Schema portion of the response, though. Here's an example of that.
swagger: '2.0'
info:
title: Test API
version: '1'
basePath: /api/v1
schemes:
- https
produces:
- application/json
paths:
/users:
get:
summary: Collection of users
tags:
- users
responses:
200:
description: A list of Users
schema:
$ref: "#/definitions/Users"
500:
$ref: "#/responses/BadRequest"
definitions:
User:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
Users:
type: array
items:
$ref: "#/definitions/User"
Response:
type: object
required:
- code
- message
properties:
code:
type: integer
description: The success code, 0 or -1.
message:
type: string
description: The description message for this success code
errors:
type: array
description: A map of errors within the request. Keyed by the parameter name and the values are the error details
BadRequest:
type: object
required:
- validationErrors
properties:
validationErrors:
type: array
items:
type: string
responses:
NonSuccess:
description: Generic response for a non-success
schema:
$ref: "#/definitions/Response"
BadRequest:
description: Invalid request parameters
schema:
allOf:
- $ref: "#/definitions/Response"
- $ref: "#/definitions/BadRequest"
I Have this YAML code of swagger and I need to create my own type (named MyOwnType).
If I use "MyOwnType" a compilation error occurs.
paths:
/in/total:
get:
summary: My summary.
description: My description.
parameters:
- name: total
in: query
description: Total.
required: true
type: MyOwnType # -- THIS LINE OCCURS ERROR --
format: MyOwnType
responses:
201:
description: Respose
schema:
$ref: '#/definitions/MyOwnType'
definitions:
MyOwnType:
properties:
var:
type: string
description: data.
I created a definition "MyOwnType" and I can use like that: "$ref: '#/definitions/MyOwnType'" in schema.
But how can I use the "MyOwnType" definition on a parameter type?
A query parameter can not have a JSON Schema. If you want to have schema for your parameter you should change in of your parameter to body or formData and use schema key:
swagger: '2.0'
info:
version: 0.0.0
title: '<enter your title>'
paths:
/in/total:
get:
summary: My summary.
description: My description.
parameters:
- name: total
in: body
description: Total.
required: true
schema:
$ref: '#/definitions/MyOwnType'
responses:
201:
description: Respose
schema:
$ref: '#/definitions/MyOwnType'
definitions:
MyOwnType:
properties:
var:
type: string
description: data.