Hi I have the following schema, which contains a map of string and I have included some examples. The JSON display works but XML display not. Is there a way to workaround this?
paths:
/somePath:
get:
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SomeMap'
application/xml:
schema:
$ref: '#/components/schemas/SomeMap'
components:
schemas:
SomeMap:
type: object
additionalProperties:
type: string
example:
'key_1': 'value_1'
'key_2': 'value_2'
'key_3': 'value_3'
Output in JSON:
{
"key_1": "value_1",
"key_2": "value_2",
"key_3": "value_3"
}
Output in XML:
<?xml version="1.0" encoding="UTF-8"?>
<SomeMap>
<additionalProp>string</additionalProp>
</SomeMap>
Expected output in XML:
<?xml version="1.0" encoding="UTF-8"?>
<SomeMap>
<key_1>value_1</key_1>
<key_2>value_2</key_2>
<key_3>value_3</key_3>
</SomeMap>
Using Swagger 3.0.
Add the XML example as a response example instead:
paths:
/somePath:
get:
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SomeMap'
application/xml:
schema:
$ref: '#/components/schemas/SomeMap'
example: |
<?xml version="1.0" encoding="UTF-8"?>
<SomeMap>
<key_1>value_1</key_1>
<key_2>value_2</key_2>
<key_3>value_3</key_3>
</SomeMap>
Related
post:
tags:
- Customer
summary: Create Customer
description: Create Customer
operationId: Customer
parameters:
- in: header
name: operationId
description: Content Type
required: true
schema:
type: string
example: Customer
requestBody:
$ref: '#/components/requestBodies/createCustomer'
responses:
'200':
$ref: '#/components/responses/postsuccess'
'400':
$ref: '#/components/responses/postfailed'
components:
headers:
Content-Type:
description: request content type
required: true
schema:
type: string
example: application/json
How can I add a header from component in Swagger?
In OpenAPI, Content-Type is a special header that cannot be described as a header parameter. Instead, it's defined using request/response media types.
Example for a POST request body:
post:
requestBody:
required: true
content:
application/json: # <--- This line defines the "Content-Type" header in requests
schema:
$ref: '#/components/schemas/MyObject'
Or when $ref'erencing the requestBody from components (as in your example), you'd have something like:
post:
requestBody:
$ref: '#/components/requestBodies/createCustomer'
...
components:
requestBodies:
createCustomer:
required: true
content:
application/json: # <--- This defines the "Content-Type" header in requests
schema:
$ref: '#/components/schemas/Customer'
I'm trying to create an enum as a reusable object in my swagger and swagger is erroring with:
Structural error at components.schemas.Project.properties.location
should NOT have additional properties
additionalProperty: schema
Jump to line 47
I have the enum specified in the components/schemas section and I am then referencing it using $ref: '#/components/schemas/Registry'. I was trying to follow the example here: https://swagger.io/docs/specification/data-models/enums/
This is the full swagger file:
openapi: 3.0.3
info:
title: My API
description: |-
Blah
contact:
email: support#example.com
version: 1.0.0
externalDocs:
description: Find out more about blah
url: http://blah.io
paths:
/credits-received:
post:
tags:
- Credits Received
operationId: creditsReceived
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreditsReceivedData'
required: true
responses:
'200':
description: Successful operation
components:
schemas:
CreditsReceivedData:
required:
- project
type: object
properties:
project:
$ref: '#/components/schemas/Project'
Project:
required:
- name
- registry
type: object
properties:
name:
type: string
example: "Project 1"
registry:
type: string
example: "My Registry"
schema:
$ref: '#/components/schemas/Registry'
Registry:
type: string
enum:
- My Registry 1
- My registry 2
I solved this by replacing
registry:
type: string
example: "My Registry"
schema:
$ref: '#/components/schemas/Registry'
with
registry:
$ref: '#/components/schemas/Registry'
Basically remove the schema attribute, just put the $ref directly under the property (registry in this case).
Swagger.yml
swagger: "2.0"
info:
version: "0.0.1"
title: Movie DB
# during dev, should point to your local machine
host: localhost:8000
# 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:
/movies:
# binds a127 app logic to a route
x-swagger-router-controller: movies
get:
description: Returns 'Hello' to the caller
# used as the method name of the controller
operationId: index
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/MovieListBody"
# responses may fall through to errors
default:
description: Error
schema:
$ref: "#/definitions/ErrorResponse"
/swagger:
x-swagger-pipe: swagger_raw
# complex objects have schema definitions
post:
description: Creates a new movie entry
operationId: create
parameters:
- name: movie
required: true
in: body
description: a new movie details
schema:
$ref: "#/definitions/MovieBody"
responses:
"200":
description: a successfully stored movie details
schema:
$ref: "#/definitions/MovieBody"
default:
description: Error
schema:
$ref: "#/definitions/ErrorResponse"
definitions:
MovieListBody:
required:
- movies
properties:
movies:
type: array
items:
$ref: "#/definitions/Movie"
Movie:
required:
- title
- gener
- year
properties:
title:
type: string
gener:
type: string
year:
type: integer
MovieBody:
required:
- movie
properties:
movie:
$ref: "#/definitions/Movie"
ErrorResponse:
required:
- message
properties:
message:
type: string
I Get this error:
Route defined in Swagger specification (/movies) but there is no defined post operation
I am new to this concept of Swagger API. I tried crud operation in Swagger API. The get method is working fine, but I tried post showing this type of issue. I tried step by step watching Swagger API videos. I tried get function is data successfully retrieved in db.but I tried post data to mongodb using Swagger API it's throwing this type of error....
How to fix it? Can anyone suggest any solution?
You don't need the /swagger node, just a post node at the same level as the get node under /movies path.
POST and GET are operations that can be performed on the 'movies' endpoint.
At present, your swagger supports GET /movies/ and POST /swagger/ as you've got a path called 'swagger'.
The structure should become:
paths:
/movies:
get:
# All the get properties
post:
# All the post properties
definitions:
# All the definitions you need
And here's an updated copy of your swagger:
swagger: "2.0"
info:
version: "0.0.1"
title: Movie DB
# during dev, should point to your local machine
host: localhost:8000
# 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:
/movies:
# binds a127 app logic to a route
x-swagger-router-controller: movies
get:
description: Returns 'Hello' to the caller
# used as the method name of the controller
operationId: index
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/MovieListBody"
# responses may fall through to errors
default:
description: Error
schema:
$ref: "#/definitions/ErrorResponse"
post:
description: Creates a new movie entry
operationId: create
parameters:
- name: movie
required: true
in: body
description: a new movie details
schema:
$ref: "#/definitions/MovieBody"
responses:
"200":
description: a successfully stored movie details
schema:
$ref: "#/definitions/MovieBody"
default:
description: Error
schema:
$ref: "#/definitions/ErrorResponse"
definitions:
MovieListBody:
required:
- movies
properties:
movies:
type: array
items:
$ref: "#/definitions/Movie"
Movie:
required:
- title
- gener
- year
properties:
title:
type: string
gener:
type: string
year:
type: integer
MovieBody:
required:
- movie
properties:
movie:
$ref: "#/definitions/Movie"
ErrorResponse:
required:
- message
properties:
message:
type: string
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