Writing OpenAPI Specification

2022 Apr 26

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.

Swagger

Read more