Visual Studio Code extension
I edit OpenAPI specification files in Visual Studio Code with extensions OpenAPI (Swagger) Editor and Swagger Viewer. With these extension, Visual Studio Code can edit, validate, preview OpenAPI specification files and try out API in the preview pages.
If you like these extensions, you can add them as workspace recommendations.
$ tree .vscode/
.vscode/
└── extensions.json
$ cat .vscode/extensions.json
{
// See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
// Extension identifier format: ${publisher}.${name}. Example: vscode.csharp
// List of extensions which should be recommended for users of this workspace.
"recommendations": [
"Arjun.swagger-viewer",
"42Crunch.vscode-openapi"
],
// List of extensions recommended by VS Code that should not be recommended for users of this workspace.
"unwantedRecommendations": [
]
}
The .vscode directory can be checked into the VCS to share with others.
Using $ref
The $ref can be mixed with “in-place” definitions.
parameters:
# Define a parameter in place
- in: path
name: id
required: true
description: The primary key.
schema:
type: integer
example: 21
# Local Reference, # means go to the root of the current document
- $ref: '#/components/parameters/ParaFoo'
# Remote Reference
- $ref: 'parameters.yaml#/components/parameters/ParaBar'
URL Reference is also supported. See more at the Using $ref documentation.
Below is another example, use $ref to refer to a shared definition in both List ang Get API.
List API responds with {"data": [{},{},...]}, while Get API responds with {"data": {}}.
# List API 200 response
responses:
200:
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/OrderObject"
# Get API 200 response
responses:
200:
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/OrderObject"
Any sibling elements of a $ref are ignored
parameters:
- $ref: '#/components/parameters/PK'
example: 21
The example in above definition is ignored. So, it does NOT equal to below definition.
parameters:
- in: path
name: id
required: true
description: The primary key.
schema:
type: integer
example: 21
The description fields
Long description can be written in YAML multiline string.
required: false
description: >
The very long description can be written using this YAML multiline string
format. See more of this YAML syntax at [this link](https://yaml-multiline.info/).
The `description` field also support **markdown** formatting.
Most of objects in OpenAPI specification have a description field.
The description fields support rich text formatting via markdown syntax.
As per the “Rich Text Formatting” section of the specification,
support, at a minimum, markdown syntax as described by CommonMark 0.27.
Most of objects in OpenAPI specification have a summary field.
Usually summary fields are for short summary, while description fields are
for verbose explanation.
Adding Examples
Multiple examples of a parameter.
in: query
name: fields
schema:
type: string
examples:
Get all top-level, second-level and third-level fields:
value: "*.*.*"
summary: Example can have additional description too.
Get all top-level fields:
value: "*"
When “try it out” API in the VS Code preview or Swagger UI page, these examples can be chosen in the dropdown list.
See more, including request and response examples, object and property examples, array examples, and reusing example, at the Adding Examples doc.
Date types and format
Date types can specify their format. For example, string has a date-time format.
uploaded_on:
type: string
format: date-time
description: When the file was uploaded.
example: "2022-04-26T06:36:24+00:00"
Free-Form Object
Some API may not have a pre-defined schema for its response.
For example the fields of an entity is completely configured by users.
Define a free-form object (arbitrary property/value pairs) by not specifying its properties.
schemas:
ItemObject:
description: Items don't have a pre-defined schema.
type: object
example:
id: 1
title: "Hello, world!"
See more at the “Free-Form Object” section of the Data Types doc.
The components section
The components section can be used to define common parameters, schemas (data models),
responses, examples and others.
API using Bearer Authentication
To describe API is using “Bearer Authentication”, simply defining a “header” parameter like below may not work in some situations.
parameters:
- in: header
name: Authentication
With the above definition, even if you input a valid value for the Authentication
header, the “Try it out” in the Swagger UI page will still not work.
The correct way is first to define a security schema in the components section.
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
Then use the BearerAuth in the API level or root level.
paths:
/orders:
get:
tags:
- Order
summary: List all orders.
security:
- BearerAuth: []
Now in the VS Code preview page, or Swagger UI page, click the “Authorize” button
to input the “bearer token”, and then click the “Try it out” to test the API.
The Authentication header will be set with correct bearer token to authorize
the API call.
See more at Authentication and Authorization and Bearer Authentication.