I am using swagger for documenting my REST API service.
I have an specific input that I provide to the service.
I am creating YAML code by myself using swagger editor. The issue I am facing is I am not able to get the input type as XML, it by default takes JSON.
Is there any issue in my yaml code. The code is given below:
swagger: "2.0"
info:
title: Order Update to Dealers
description: API description in Markdown.
version: 1.0.0
host: #Host name cannot be specified here
basePath: /api/OrderUpdate
schemes:
- http
paths:
/GetFullOrderAcknowlegement:
post:
summary: Returns a list of users.
consumes:
- application/xml
produces:
- text/plain
parameters:
- in: body
name: DealerInput
description: Optional extended description in Markdown.
schema:
properties:
DealerID:
type: string
PONumber:
type: string
responses:
201:
description: Created
200:
schema: {}
description: OK
401:
schema: {}
description: Authorization information is missing or invalid.
This was a bug in Swagger Editor 3.3.0 and Swagger UI 3.11.0. It was fixed in Editor 3.3.1 and UI 3.12.0 (released on March 4, 2018).
As a workaround, you can download Editor v3.2.9 and run it locally by opening the index.html file in your browser.
Related
I'm encountering a really weird bug in swagger.
When trying to render a component with a property called 'entries', the compiler breaks with the error:
The provided definition does not specify a valid version field.
Please indicate a valid Swagger or OpenAPI version field.
Supported version fields are swagger: "2.0" and those that
match openapi: 3.0.n (for example, openapi: 3.0.0).
An example that will return this error:
openapi: 3.0.2
info:
title: API Documentation
version: '1'
paths:
/v1/detail/:
get:
tags:
- clips
summary: Get details
operationId: Create Detail
description: Retrieve details
parameters: []
responses:
'200':
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/Clip'
description: ''
components:
schemas:
Clip:
type: object
properties:
entries:
type: string
example: 'abc'
But by renaming entries to something else, like 'x_entries', the compiler is OK.
I couldn't find any reference to 'entries' in the openapi documentation, although I could be wrong here. Does anyone know why 'entries' as an property in a component causes an issue?
It was a bug in Swagger UI v. 3.25.3 and Swagger Editor v. 3.8.3.
Fixed in UI v. 3.25.4 and Editor v. 3.9.0.
I'm writing an Open API 3.0 spec and trying to get response links to render in Swagger UI v 3.18.3.
Example:
openapi: 3.0.0
info:
title: Test
version: '1.0'
tags:
- name: Artifacts
paths:
/artifacts:
post:
tags:
- Artifacts
operationId: createArtifact
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
201:
description: create
headers:
Location:
schema:
type: string
format: uri
example: /artifacts/100
content:
application/json:
schema:
type: object
properties:
artifactId:
type: integer
format: int64
links:
Read Artifact:
operationId: getArtifact
parameters:
artifact-id: '$response.body#/artifactId'
/artifacts/{artifact-id}:
parameters:
- name: artifact-id
in: path
required: true
schema:
type: integer
format: int64
get:
tags:
- Artifacts
operationId: getArtifact
responses:
200:
description: read
content:
application/octet-stream:
schema:
type: string
format: binary
renders a link like this:
Is this expected? I ask because the operationId is exposed on the UI and parameters is shown as a JSON reference make it seem like something is not displaying properly. I would have expected a hyperlink or something to take me to the appropriate section in the Swagger web page that corresponds to the API being referenced by the link.
Yes this is how Swagger UI currently renders OAS3 links. Rendering of links is one of the things on their OAS3 support backlog:
OAS 3.0 Support Backlog
This is a collection ticket for OAS3 specification features that are not yet supported by Swagger-UI.
...
[ ] Links can't be used to stage another operation
[ ] Link-level servers are not available for executing requests
I am creating a well-organized OAS3 swagger documentation on swaggerhub. For every endpoint i am writing all possible answers like 200, 201, 204, 400, 401, 403, 404, 500 etc. In addition all methods have default parameters like X-Language-Code etc.
I am in such a place that the responses, models, parameters I use now begin to repeat themselves in each file. After a little research i learnt that i can create a domain and remote absolute url references to them.
There is no error when i used the 'definition's remotely like this:
/example:
get:
#some other informations here
responses:
200:
description: 'example description'
content:
application/json:
schema:
$ref: 'https://remote.example/url/2.0#/definitions/ExampleResponse'
But, apparently you can not use $ref keyword right below responses or 400 etc.. keyword like this:
This one not getting error but not rendering the remote reference
responses:
400:
$ref: 'https://remote.example/url/2.0#/responses/Error400'
or this:
This one gives error
responses:
$ref: 'https://remote.example/url/2.0#/responses'
Even, i can not use 'parameters' as i expected:
/example:
get:
parameters:
- languageCode:
$ref: 'https://remote.example/url/2.0#/parameters/languageCode'
/example:
get:
parameters:
- $ref: 'https://remote.example/url/2.0#/parameters/'
I dont want to rewrite all reference definitions below every documentation.
I am confused about using and referencing 'domain's. Can someone explain or referencing a document about this situations since i couldn't found any documentation about it.
Update: OpenAPI 3.0 domains are now supported in SwaggerHub.
As of December 2018, SwaggerHub domains only support the OpenAPI 2.0 syntax but not OpenAPI 3.0. OpenAPI 3.0 and 2.0 use slightly different syntax for parameters, responses, etc., this means you cannot reference an OAS2 domain from an OAS3 API definition.
The workaround is to create another OpenAPI 3.0 API in SwaggerHub and use it as a "domain". You'll need to add a dummy header with openapi: 3.0.0, the info section and empty paths: {} to make the validator happy.
openapi: 3.0.0
info:
title: Common components
version: 1.0.0
paths: {}
# Put your common components here:
components:
schemas:
...
parameters:
...
responses:
...
Then you can reference components from this "domain" using the usual $ref syntax:
$ref: 'https://api.swaggerhub.com/apis/USERNAME/API-NAME/VERSION#/components/responses/Error400'
Make sure the hostname in $refs is API.swaggerhub.com (not APP.swaggerhub.com) and the link contains /apis/ (not /domains/).
How do I set a content type other than application/json for a body parameter in Swagger UI 3.x using a Swagger (Open API) 2.0 YAML definition file?
My YAML file is as follows, with the consumes element set to application/json+fhir and application/xml+fhir:
swagger: '2.0'
info:
title: Test
version: '1.0'
host: 'server.com'
basePath: /fhir
schemes:
- http
paths:
/Patient/$getrecordsection:
post:
tags:
- Get record section
summary: Retrieve a care record section
consumes:
- application/json+fhir
- application/xml+fhir
produces:
- application/json+fhir
- application/xml+fhir
parameters:
- in: body
name: body
description: ''
required: true
schema:
$ref: '#/definitions/GetRecordSection'
responses:
'200':
description: OK
'400':
description: Bad request
definitions:
GetRecordSection:
type: object
properties:
resourceType:
type: string
default: "Parameters"
parameter:
type: string
example:
resourceType: "Parameters"
parameter:
- name: "patientIdentifier"
valueIdentifier:
system: "http://fhir.provider.net/Id/patient-identifier"
value: "9999999999"
- name: "recordSection"
valueCodeableConcept:
coding:
- system: "http://fhir.provider.net/ValueSet/record-section"
code: "ALL"
xml:
name: Parameters
However, the Swagger UI only shows application/json as the body parameter content type:
I'm using the current latest Swagger UI build - 3.11.0.
This is a problem with Swagger UI, rather than the Swagger Editor (though I know the two share a significant number of components), and so the root cause could be the same.
This is a bug in the 3.11.0 version of Swagger UI, using Swagger/Open API 2.0:
https://github.com/swagger-api/swagger-ui/issues/4257
This is a simplified version of my OpenAPI 3.0 definition I'm viewing on the Swagger Editor online. I am trying to have the two responses for error codes 401 and 403, that share the same schema, show different examples - this doesn't seem to work and I still see the referenced type as example.
Can you help me figuring out what's wrong with the definitions?
openapi: 3.0.0
info:
version: '1.0'
title: A service
paths:
/doSomething:
post:
requestBody:
content:
application/json:
schema:
type: string
example: A string
responses:
401:
$ref: '#/components/responses/Unauthorized'
403:
$ref: '#/components/responses/Denied'
components:
responses:
Unauthorized:
description: The endpoint cannot be reached because the request is not authorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: unauthorized
Denied:
description: The request's authorizations don't match the required ones needed to access the resource
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: permissions denied
schemas:
Error:
type: object
properties:
error:
type: string
Your definition is correct, and the response example show up in Swagger Editor 3.6.5+ and Swagger UI 3.17.4+. Also, multiple examples are supported in Swagger UI 3.23.0+ and Editor 3.6.31+.
I am not sure whether this is at the heart of your problem but I noticed that the HTTP status codes in your path respone sections aren't given enclosed in quotation marks. The OpenAPI specification v3.x (in contrast to v2.x) makes this mandatory which you might want to look up here:
https://swagger.io/specification/#responses-object
https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#responses-object