I am using https://app.swaggerhub.com/ to develop my api endpoints. I have set it up in webroot/swagger folder. This folder contains
favicon-16x16.png
oauth2-redirect.html
swagger-ui-bundle.js.map
swagger-ui.js
swagger-ui-standalone-preset.js.map
favicon-32x32.png
swagger.json
swagger-ui.css
swagger-ui.js.map
index.html
swagger-ui-bundle.js
swagger-ui.css.map
swagger-ui-standalone-preset.js
What i do is export json_resolved for app... to my repo and it loads fine. problem is when i click on an endpoint and want to load the endpoint specifically on first load. for example
loading http://exampledomain.com/swagger/#/giant/addCm on 1st load would error
Unable to render this definition
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).
r {name: "YAMLException", reason: "end of the stream or a document separator is expected", mark: o, message: "end of the stream or a document separator is expec… box-sizing: border-box;↵ ^", stack: "YAMLException: end of the stream or a document sep…lreply.com/swagger/swagger-ui-bundle.js:51:29161)"}
name: "YAMLException"
reason: "end of the stream or a document separator is expected"
mark: o {name: null, buffer: "<!-- HTML for static distribution bundle build -->…dow.ui = ui↵ }↵ </script>↵ </body>↵</html>↵", position: 432, line: 12, column: 18}
message: "end of the stream or a document separator is expected at line 13, column 19:↵ box-sizing: border-box;↵ ^"
stack: "YAMLException: end of the stream or a document separator is expected at line 13, column 19:↵ box-sizing: border-box;↵ ^↵ at M (https://dev1.domain.com/swagger/swagger-ui-bundle.js:79:71772)↵ at N (https://dev1.domain.com/swagger/swagger-ui-bundle.js:79:71870)↵ at Y (https://dev1.domain.com/swagger/swagger-ui-bundle.js:79:85578)↵ at $ (https://dev1.domain.com/swagger/swagger-ui-bundle.js:79:85933)↵ at Z (https://dev1.domain.com/swagger/swagger-ui-bundle.js:79:86083)↵ at Object.e.exports.safeLoad (https://dev1.domain.com/swagger/swagger-ui-bundle.js:79:86413)↵ at https://dev1.domain.com/swagger/swagger-ui-bundle.js:6:6349↵ at Object.dispatch (https://dev1.domain.com/swagger/swagger-ui-bundle.js:1:60251)↵ at dispatch (<anonymous>:1:28545)↵ at Object.parseToJson (https://dev1.domain.com/swagger/swagger-ui-bundle.js:51:29161)"
__proto__: Error
openapi: 3.0.0
info:
description: |
# Requirements
* domain Service Account
* CORS Proxy | We can add your FQDN to the whitelist
version: 2.0.0
title: CCP API
# put the contact info for your development or API team
contact:
email: m.uddin#reply.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
# tags are used for organizing operations
tags:
- name: dcsn
- name: find
- name: firewall
- name: lists
- name: services
- name: vpf
- name: cm
- name: giant
security:
- BasicAuth: []
paths:
/iwsapi/admin/rename/comms/matrices:
post:
tags:
- cm
summary: Rename Cm
operationId: renameCm
description: Rename Cm
requestBody:
#description: add column filters
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/CmForm'
responses:
200:
description: Verify Policy Flow
content:
application/json:
schema:
$ref: '#/components/schemas/Cm'
401:
description: invalid user
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
422:
description: invalid input, object invalid
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- BasicAuth: []
components:
securitySchemes:
BasicAuth:
type: http
scheme: basic
headers:
xPaginationCount:
description: Total no. of records found.
schema:
type: integer
xPaginationLimit:
description: No. of records to limit fetch.
schema:
type: integer
xPaginationOffset:
description: Start fetch from row
schema:
type: integer
schemas:
Error:
type: object
items:
type: object
properties:
header:
type: object
properties:
error:
type: boolean
message:
type: string
example:
header:
error: true
message: error message if available
CmForm:
type: object
required:
- comms_matrix_id
properties:
comms_matrix_id:
type: number
example: 1
remedy_inc:
type: string
description: 15 characters long, starts with AAS|INC|CRQ|TAS|RLM, continues with 12 digits
example: AAS111111111111
remedy_status:
type: string
enum: [Assigned, Cancelled, Closed, In Progress, Pending, Resolved]
example: Assigned
remedy_team:
type: string
example: team
remedy_status_reason:
type: string
example: free text
Cm:
type: object
items:
type: object
properties:
body:
type: object
properties:
recordset:
type: object
properties:
record:
type: array
items:
type: object
properties:
id:
type: number
service_id:
type: number
filename:
type: string
visible_lines:
type: number
aggregated_flows:
type: number
security_flows:
type: number
routing_flows:
type: number
error_flows:
type: number
security_permit:
type: number
security_deny:
type: number
security_exemption:
type: number
security_prevention:
type: number
routing_permit:
type: number
routing_deny:
type: number
routing_exemption:
type: number
routing_prevention:
type: number
routing_issues:
type: number
uploaded_by:
type: string
ts_updated:
type: string
ts_created:
type: string
frozen:
type: boolean
deleted:
type: boolean
warning_flows:
type: number
remedy_status:
type: string
remedy_inc:
type: string
cm_sox_approval_id:
type: number
remedy_team:
type: string
remedy_status_reason:
type: string
metadata:
type: object
properties:
num_rows:
type: number
example:
body:
recordset:
record:
- id: 135841
service_id: 3
filename: German_Zones_Test3.xlsx
visible_lines: 48
aggregated_flows: 1
security_flows: 48
routing_flows: 1
error_flows: 0
security_permit: 48
security_deny: 48
security_exemption: 0
security_prevention: 0
routing_permit: 0
routing_deny: 0
routing_exemption: 48
routing_prevention: 0
routing_issues: null
uploaded_by: kakoullim
ts_updated: 13-Mar-20 11:55:38
ts_created: 20-Mar-03 12:14:04
frozen: 0
deleted: 0
warning_flows: 0
remedy_status: Pending
remedy_inc: INC123456789101
cm_sox_approval_id: 4550
remedy_team: null
remedy_status_reason: null
metadata:
num_rows:
1
schemes:
- https
# Added by API Auto Mocking Plugin
# basePath: /
# Added by API Auto Mocking Plugin
host: ccp.domain.com
# basePath: /vf-ccp/ccp/1.0.0
# Added by API Auto Mocking Plugin
basePath: /
# Added by API Auto Mocking Plugin
servers:
# Added by API Auto Mocking Plugin
- description: CCP-PRODSUPP
url: https://prodsupp.domain.com
- description: Sytel
url: https://dev1.domain.com
- description: CCP-TEST
url: https://test.domain.com
/swagger/index.html
...
<body>
<div id="swagger-ui"></div>
<script src="./swagger-ui-bundle.js"> </script>
<script src="./swagger-ui-standalone-preset.js"> </script>
<script>
window.onload = function() {
// Begin Swagger UI call region
const ui = SwaggerUIBundle({
url: window.location.href + "swagger.json",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
// End Swagger UI call region
window.ui = ui
}
</script>
</body>
...
Related
I am trying to add an array in my swagger 2.0 but I keep getting the following error:
Structural error at definitions.testPOST
should NOT have additional properties
additionalProperty: testRequests
I've checked the swagger documentation but I don't know what I am doing wrong. I could delete 'testRequests' but I need it.
The code is as follows:
swagger: '2.0'
info:
version: v1
title: testAPI
security:
- default: []
paths:
/testPOST:
post:
summary: test
description: test
parameters:
- in: body
name: Payload
description: test
required: true
schema:
$ref: '#/definitions/testPOST'
responses:
'201':
description: Success
schema:
type: object
properties:
status:
type: string
description: HTTP statuscode
title:
type: string
description: Success
detail:
type: string
description: Empty
'401':
description: No access
schema:
type: object
properties:
status:
type: string
description: HTTP statuscode
title:
type: string
description: Message invalid
detail:
type: string
description: Error message
'500':
description: Server error
security:
- default:
- testRequest
x-auth-type: Application & Application User
x-throttling-tier: Unlimited
x-wso2-application-security:
security-types:
- oauth2
optional: false
x-auth-type: Application & Application User
x-throttling-tier: Unlimited
securityDefinitions:
default:
type: oauth2
authorizationUrl: 'https://test.com'
flow: implicit
scopes:
testRequest: Scope
x-scopes-bindings:
testRequest: 'testRequest,admin'
definitions:
testPOST:
testRequests:
type: array
items:
type: object
properties:
sourceUrl:
type: string
example: 'http://example.com/test/1202112'
description: The reference url.
default: 'null'
inboundReferenceNumber:
type: string
example: '1234567890'
description: The request identifier.
default: 'null'
Can somebody please point out what I am doing wrong? Thanks in advance!
If the request body is supposed to be just an array of objects
[
{"sourceUrl": ...},
{"sourceUrl": ...},
...
]
then the definition should be:
definitions:
testPOST: # Remove the "testRequests:" line from here
type: array
items:
..
If the request body is supposed to be an object with the testRequests property whose value is an array
{
"testRequests": [
{"sourceUrl": ...},
{"sourceUrl": ...},
...
]
}
then the definition should be:
definitions:
testPOST:
type: object
properties:
testRequests:
type: array
items:
type: object
properties:
sourceUrl:
...
inboundReferenceNumber:
...
In my Swagger documentation, I have to use same pattern multiple time. Currently, it is placed duplicated.
One thing I improved is that making common parameter (by declaring it inside components). But couldn't find anything to avoid this duplicate pattern between parameters and schemas.
Is there any way, I can use declare this pattern once and re-use it wherever it's needed?
My Swagger looks something like:
openapi: 3.0.3
info:
title: My System
description: Self contained system
version: 1.0.0
servers:
- url: /a/{aId}/
description: Contains the partition
security:
- bearerAuth: []
paths:
"/x/{xId}/y/{yId}/z/{zId}":
get:
x-horizon-permission: "geo.floorplan.read"
tags:
- myTag
operationId: getValue
description: Get Value
parameters:
- name: xId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
- name: yId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
- name: zId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
responses:
"200":
description: OK
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Response'
patch:
tags:
- myTag
operationId: Update
description: Update Data
parameters:
- name: xId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
- name: yId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
- name: zId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Request'
responses:
"200":
description: OK
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Response'
components:
schemas:
Request:
type: object
properties:
data:
type: object
properties:
type:
type: string
id:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
Response:
type: object
properties:
links:
type: object
properties:
self:
type: string
data:
$ref: '#/components/schemas/Data'
Data:
type: object
properties:
type:
type: string
id:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
GeometryError:
type: object
required:
- code
- status
- title
properties:
id:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
status:
type: string
example: 400
title:
type: string
detail:
type: string
meta:
type: object
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
Define a schema with this pattern:
components:
schema:
UUID:
type: string
format: uuid # for tools/codegens that have built-in support for UUIDs
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
Then you can reference this schema from other schemas and parameter definitions:
parameters:
- name: xId
in: path
required: true
schema:
$ref: '#/components/schemas/UUID' # <-----
- name: yId
in: path
required: true
schema:
$ref: '#/components/schemas/UUID' # <-----
...
schemas:
Request:
type: object
properties:
data:
type: object
properties:
type:
type: string
id:
$ref: '#/components/schemas/UUID' # <-----
I am trying to use Swagger. Below is the swagger.yml file.
swagger: "2.0"
basePath: /myapp/api
info:
description: My description
title: My title
version: 0.1.0
produces:
- application/json
consumes:
- application/json
schemes:
- http
paths:
/contract:
get:
operationId: "Get contract"
description: Get information
parameters:
- in: path
name: contractId
description: ID
required: true
schema:
type: integer
responses:
200:
description: Information...
schema:
$ref: "#/definitions/contract"
404:
description: "Not found."
post:
operationId: "Create"
parameters:
- in: body
name: contractId
schema:
$ref: '#/definitions/requestBodies/contract'
responses:
200:
description: Success...
400:
description: Problem...
definitions:
contract:
title: Contract
type: object
properties:
name:
title: Name
type: string
services:
title: Services
type: array
items:
title: Service
$ref: '#/definitions/service'
xyz:
title: Xyz
$ref: '#/definitions/virtualMachine'
service:
title: Service
type: object
properties:
containerName:
title: ContainerName
type: string
...
contracts:
title: Contracts
type: array
items:
title: Contract
$ref: '#/definitions/contract'
xyz:
title: Xyz
type: object
properties:
serverId:
title: ServerID
type: string
contractId:
title: ContractID
type: uuid
...
requestBodies:
contract:
content:
application/json:
schema:
$ref: '#/definitions/contract'
When I try to generate the documentation, I get the following error:
swagger generate server -f swagger.yml
2020/10/26 15:43:31 validating spec /home/dalton/workspace/.../.../swagger.yml
The swagger spec at "/home/dalton/workspace/.../.../swagger.yml" is invalid against swagger specification 2.0. see errors :
- definitions.requestBodies.contract in body is a forbidden property
- "definitions.xyz.properties.contractId.type" must validate at least one schema (anyOf)
- definitions.xyz.properties.contractId.type in body must be of type array: "string"
What am I doing wrong?
To make this code pass in the Swagger validation, I had to:
Remove the schema in the contractId parameter (get method);
Remove the requestBodies definition and change the schema in the contract parameter (post method);
Change the type of the contractId in the Xyz definition (the uuid type is not supported by the version 2 of Swagger).
The fixed code is below:
swagger: "2.0"
basePath: /myapp/api
info:
description: My description
title: My title
version: 0.1.0
produces:
- application/json
consumes:
- application/json
schemes:
- http
paths:
/contract:
get:
operationId: "Get contract"
description: Get information
parameters:
- in: path
name: contractId
description: ID
required: true
type: integer
responses:
200:
description: Information...
schema:
$ref: "#/definitions/contract"
404:
description: "Not found."
post:
operationId: "Create"
parameters:
- in: body
name: contractId
schema:
$ref: '#/definitions/contract'
responses:
200:
description: Success...
400:
description: Problem...
definitions:
contract:
title: Contract
type: object
properties:
name:
title: Name
type: string
services:
title: Services
type: array
items:
title: Service
$ref: '#/definitions/service'
xyz:
title: Xyz
$ref: '#/definitions/virtualMachine'
service:
title: Service
type: object
properties:
containerName:
title: ContainerName
type: string
...
contracts:
title: Contracts
type: array
items:
title: Contract
$ref: '#/definitions/contract'
xyz:
title: Xyz
type: object
properties:
serverId:
title: ServerID
type: string
contractId:
title: ContractID
type: string
format: uuid
Maybe you can try to edit your swagger.yml in the online Swagger Editor.
I have the following API definition in SwaggerHub:
swagger: '2.0'
info:
description: defaultDescription
version: '0.1'
title: defaultTitle
host: swapi.co
paths:
/api/people:
get:
produces:
- application/json
parameters:
- name: search
in: query
required: false
type: string
x-example: luke
responses:
'200':
description: Definition generated from Swagger Inspector
schema:
$ref: '#/definitions/Model0'
responseSchema:
$ref: '#/definitions/Model0'
definitions:
Results:
properties:
name:
type: string
height:
type: string
mass:
type: string
hair_color:
type: string
skin_color:
type: string
eye_color:
type: string
birth_year:
type: string
gender:
type: string
homeworld:
type: string
films:
type: array
items:
type: string
species:
type: array
items:
type: string
vehicles:
type: array
items:
type: string
starships:
type: array
items:
type: string
created:
type: string
edited:
type: string
url:
type: string
Model0:
properties:
count:
type: integer
format: int32
next:
type: object
previous:
type: object
results:
type: array
items:
$ref: '#/definitions/Results'
I cannot make this basic GET command to bring back the data I'm seeking. It only returns this:
TypeError: Failed to fetch
I'm unsure if it's a syntax issue, or possibly spacing, but I'm also getting an error for line 19 that reads:
should NOT have additional properties
additionalProperty: responseSchema, description, schema
Any ideas what is wrong?
https://swapi.co seems to be HTTPS-only, so you need to add
schemes:
- https
to you API definition to specify the protocol for requests.
but I'm also getting an error for line 19 that reads: "should NOT have additional properties additionalProperty: responseSchema, description, schema".
Remove these lines:
responseSchema:
$ref: '#/definitions/Model0'
There's no responseSchema keyword in OpenAPI.
Working on writing an API spec for my service with swagger. I'm using a model definition ('#/definitions/prototype') as the body parameter of both the POST /prototypes and PATCH /prototypes/:id routes.
How do you specify that the PATCH route only accepts a subset of the properties in the body of the request that the POST route does? For example, I want the PATCH /instances/:id route to only allow modification of the mobileDeviceId prototypes property.
swagger: "2.0"
info:
title: ""
description: ""
version: "1.0.0"
host: foo.example.com
schemes:
- https
basePath: /v1
produces:
- application/json
consumes:
- application/json
paths:
/prototypes:
post:
summary: Create new prototype
parameters:
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/Prototype"
responses:
201:
description: Success
schema:
$ref: "#/definitions/SuccessCreated"
403:
description: Prototype limit exceeded error
schema:
$ref: "#/definitions/Error"
default:
description: Unexpected error
schema:
$ref: "#/definitions/Error"
/prototypes/{id}:
patch:
summary: Update an existing prototype's properties
parameters:
- name: id
in: path
type: number
description: ID property of a prototype
required: true
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/Prototype"
responses:
200:
description: Success
definitions:
Prototype:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
mobileDeviceId:
type: number
SuccessCreated:
type: object
description: Returned as response to successful resource create request
properties:
code:
type: number
default: 201
message:
type: string
Error:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
fields:
type: string
Swagger uses json-schema: http://json-schema.org
$refs provide you w/ a way to repeat existing json-schema at a new path.
Notice that you are using a $ref for patch/parameters/-name:prototype/schema.
You can create a new definition just for patch in the definitions section and reference it instead
swagger: "2.0"
info:
title: ""
description: ""
version: "1.0.0"
host: foo.example.com
schemes:
- https
basePath: /v1
produces:
- application/json
consumes:
- application/json
paths:
/prototypes:
post:
summary: Create new prototype
parameters:
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/Prototype"
responses:
201:
description: Success
schema:
$ref: "#/definitions/SuccessCreated"
403:
description: Prototype limit exceeded error
schema:
$ref: "#/definitions/Error"
default:
description: Unexpected error
schema:
$ref: "#/definitions/Error"
/prototypes/{id}:
patch:
summary: Update an existing prototype's properties
parameters:
- name: id
in: path
type: number
description: ID property of a prototype
required: true
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/PatchPrototype"
responses:
200:
description: Success
definitions:
Prototype:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
mobileDeviceId:
type: number
PatchPrototype:
type: object
properties:
mobileDeviceId:
type: number
SuccessCreated:
type: object
description: Returned as response to successful resource create request
properties:
code:
type: number
default: 201
message:
type: string
Error:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
fields:
type: string