I am trying to implement HTTP Basic Auth on my Swagger page.
the docs for securityDefinitions give an example:
type: http
scheme: basic
however when I add it to my YAML file like this:
securityDefinitions:
type: http
scheme: basic
I get an error:
What am I doing wrong?
type: http
scheme: basic
is OpenAPI 3.0 syntax (the spec you linked to is OpenAPI 3.0).
But you are using OpenAPI 2.0, so you need to use:
securityDefinitions:
BasicAuth:
type: basic
security:
- BasicAuth: []
Here is the OpenAPI 2.0 Spec:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#securitySchemeObject
And here's the Basic auth guide for 2.0:
https://swagger.io/docs/specification/2-0/authentication/basic-authentication/
Related
Running latest (and now old due to the switchover to flask REST-X) flask RESTPlus using the authorization functionality for the swagger interface with a Bearer token as follows:
authorizations = {
'apikey': {
'type': 'apiKey',
'in': 'header',
'name': 'Bearer '
}
But although the "Authorise" box comes up in the swagger interface, and I can put a token in there, it doesn't get added to the requests coming out or the curl format that swagger provides, so we can see clearly it's not being picked up. What's going on here and how do I fix it?
Make sure the code also has annotations that would add security to individual operations or globally. This is needed to actually attach the Authorization header to operations.
In other words, the generated OpenAPI definition should contain the following.
If using OpenAPI 2.0:
swagger: '2.0'
securityDefinitions:
apikey:
type: apiKey
in: header
name: Authorization
security:
- apiKey: []
If using OpenAPI 3.0:
openapi: 3.0.0
components:
securitySchemes:
apikey:
type: apiKey
in: header
name: Authorization
# or using OAS3 Bearer auth scheme
# apiKey:
# type: http
# scheme: bearer
security:
- apiKey: []
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
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.
I am trying to use Swagger to define an API that accepts an actual file and a schema object that describes the contents of a file. Here is a snippet of the Swagger YAML. However it won't validate in the Swagger Editor.
/document:
post:
summary: Api Summary
description: Api Description
consumes:
- multipart/form-data
parameters:
- name: documentDetails
in: formData
description: Document Details
required: true
schema:
$ref: '#/definitions/Document'
- name: document
in: formData
description: The actual document
required: true
type: file
The Swagger Editor throws the following validation error:
Swagger Error: Data does not match any schemas from 'oneOf'
Am I missing something? Or Is this not a supported feature of Swagger?
This is possible in OpenAPI 3.0, but not in OpenAPI/Swagger 2.0.
OpenAPI/Swagger 2.0 does not support objects in form data. Form parameters can be primitive values, arrays of primitives, and files, but not objects. So your example cannot be described using OpenAPI 2.0.
In OpenAPI 3.0, you can use:
paths:
/document:
post:
summary: Api Summary
description: Api Description
requestBody:
required: true
content:
multipart/form-data:
# Form parameters from 2.0 become body schema properties in 3.0
schema:
type: object
properties:
# Schema properties correspond to individual parts
# of the multipart request
document:
# In 3.0, files are binary strings
type: string
format: binary
description: The actual document
documentDetails:
$ref: '#/components/schemas/Document'
# The default Content-Type for objects is `application/json`
required:
- document
- documentDetails
Relevant parts of the 3.0 Specification:
Considerations for File Uploads
Special Considerations for multipart Content
swagger does not support type 'object' in formData, only as body parameters.
It is not possible using Swagger 2.0 , you can only read it as a type 'file' ,
https://swagger.io/docs/specification/2-0/file-upload/
On a related note please be aware that uploading array of files is also not supported in Swagger 2.0 but it is supported in Open API 3.0 .
https://github.com/OAI/OpenAPI-Specification/issues/254