arjun-g / vs-swagger-viewer

Swagger Viewer lets you preview and validate Swagger 2.0 and OpenAPI files as you type in Visual Studio Code.

Swagger Viewer - v3.1.2

Swagger Viewer lets you preview Swagger 2.0 and OpenAPI files as you type in Visual Studio Code. Additionally provide intellisense/linting for the files as well.

It works on swagger files in json and yaml format. Preview happens in real time as you type.

Preview

To start

• Open the swagger file and press F1.
• Run the Command Preview Swagger.

OR

• Press Shift + Alt + P

OR

• Right click file in explorer panel and click Preview Swagger

THEN

• Preview it in vscode Itself like this

Configurations

Opening In External browser

If you want to preview the changes in external browser change the settings Preview In Browser to true in User/Workspace Settings

THEN

• Run the Command Preview Swagger.

OR

• Press Shift + Alt + P

Preview will be automatically opened in default browser.

Change Default Port

Default port of the preview url can be changed by changing the Default Port value in User/Workspace Settings

Show Only File Name

In the preview title the file name along with the full path is displayed by default. It can be changed to show only the file name by changing the Show Only File Name to true in User/Workspace Settings

Change Default Host

Default host(localhost) of the preview url can be changed by changing the swaggerViewer.defaultHost value in User/Workspace Settings

Stop Swagger Viewer Preview Server

To stop the preview server simply click the status bar item.

Releases

v3.0.0 Changes

• The primary functionality of the Swagger Viewer extension would be the ability to preview Swagger and OpenAPI files.
• Swagger Viewer will just use the json schema of Swagger and OpenAPI to provide intellisense and linting. Recommend using teh extension OpenAPI (Swagger) Editor for full editing capabilities.
• Intellisense for Swagger 2.0 and OpenAPI 3.0 is available now. Added extension YAML as extensionDependencies for supporting YAML intellisense.
• Default port changed to 18512
• Upgraded swagger-ui to version 3.25.2
• Start preview server in next available port for preview if configured port is not available
• Fix for custom host config
• Ability to stop the preview server

v2.2.2 Changes

• Fixed validation issue with external refs #45 By @yuri1969 #56
• Fix for #43 By @joschiwald #59

v2.2.1 Changes

• Fixed the external refs issue #45

Known Issue

• Validator still gives a warning on relative paths. Will be fixed in next version.

v2.2.0 Changes

• Support to configure default preview host (instead of localhost) - By @beastoin #41

v2.1.0 Changes

• Replaced the deprecated vscode.previewHtml with Webview - #50
• Added configuration option to show only file name in title
• Added support for OpenAPI 3.0.3 validation - By @ackintosh #49

v2.0.2 Changes

• Fixed issues with parsing yaml due in yamljs library. Changed to js-yaml library.
• Fixed issue where validation errors are not cleared in yaml file.

v2.0.0 Changes

• Code base changed to TypeScript
• Partial validation support added
• OpenAPI Support added (Not fully tested)
• Only one server runs for the preview page
• Multiple files can be previewed at a time inside vscode
• Context menu added to the explorer to start the preview directly without opening the file
• Using files from swagger-ui-dist npm package - By @Raptor399 #36
• Multiple minor bug fixes

v1.7.0 Changes

• Fixed issue in json file parsing. - By @Zlass #27

v1.6.0 Changes

• Added support for .yaml, .yml, .json and unsaved documents. - By @DW8Reaper #21

v1.5.0 Changes

• Upgraded Swagger UI v3 for preview. - By @jienco #17

v1.4.0 Changes

• Fixed - Preview of JSON Swagger files not getting updated in realtime. - By @tmsns
• Fixed - Preview window in vs code not switching to latest file.
• Added - File name in preview window to identify which file is in preview.
• Some performance fixes

v1.3.0 Changes

• Added - Now preview swagger inside the editor itself. - By @ferreus #7
• Added - Preview inside editor by default

v1.2.0 Changes

• Added - Open button in message box. - By @pmentz #3
• Added - shortcut Shift + Alt + P to run the command
• Added - Ability to change default port from User/Workspace Settings.

Credits

Swagger Viewer utilizes the following open source projects

• Swagger Editor
• Swagger Parser
• Express
• socket.io
• yaml.js

Contributors

• Patrick Mentz (@pmentz)
• Vladimir Vainer (@ferreus)
• Jonatan Ienco (@jienco)
• @tmsns
• @DW8Reaper
• @Zlass
• @Raptor399
• @ackintosh

vs-swagger-viewer's Issues

Is it possible to avoid CORS restriction on the viewer?

I'm trying to perform GET request from the editor being shown by the viewer.
The resource is at https://gpodder.net/clientconfig.json

When I perform the GET request the editor show the error TypeError: Failed to fetch.

I believe this is a CORS restriction that is being applied because when I access http://localhost:9000 in chrome I get the same error and inspecting the console I see:

Failed to load https://gpodder.net/clientconfig.json: No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://localhost:9000' is therefore not allowed access. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.

but when I try it again on chrome with the option "--disable-web-security", where the CORS check does not apply, the request is successful.

Would it be possible to disable web security in the viewer as an option?

LOCAL WEB SERVER NOT WORKING TIME TO TIME

Hello,
i am using the preview in browser with the setting:
"swaggerViewer.previewInBrowser": true,

At the beginning is working very good but sometime (very often and i don't know when exactly) it look like the local web serve that hosts the Swagger UI stops to work.

This is the errore that i get from by browser
ERR_CONNECTION_REFUSED

I try to give again the command "Preview Swagger" but it doesn't work.

I have to restart VS Code for make it working.

Preview pane only shows "Access Denied"

When resurrecting an old project containing a swagger file, I installed the Swagger Viewer extension for the first time. I reloaded VSCode after installation, then triggerd the Preview Swagger action on the open swagger.yaml file. But the only thing I see in the preview pane is this:

AccessDeniedAccess Denied./18264904933L1373L137

Any idea what is wrong?

VSCode 1.26.1
Swagger Viewer 2.0.2
MacOS High Sierra 10.13.6

Don't collapse UI on every change

When I'm working on the definition for a particular request, I usually like to keep it expanded in the UI. Would be nice if the extension didn't collapse all requests on every change (the Swagger Editor does this nicely).

Please change the default port...

Look, this extension is used by developers, and port 9000 is like super common - even if it's configurable this is really confusing when the preview locks the port.

Unable to Parse: Missing error

Hey guys,

if I open the swagger viewer in VS Code the page remains empty/white. Opening the dev tools reveals the message: ERR Unable to parse. Without a useful hint I am not able to debug.

The swagger online editor shows no error.

Note: I'm using open api specification 3.0.1. Might this be a problem?

Extension Version: 1.5.0

EDIT: Unfortunately I can not post the .yaml file because it's an internal api that is not meant for the public (yet).

custom validation rules

Is there a way to configure this to include your own custom validation rules? For example, I want to enforce particular company editorial style rules and display feedback to the dev/writer. Similar to the way the Vale lint program does.

no error tips

Doesn't allow for multiple Swagger docs to be open

If I have two different swagger docs open in Visual Studio, the preview for both docs shows the same preview - the first document opened.

Have a look at the attachment. The left image is correct. The right is not (all fine except for the swagger contents
).

Preview displaying as blank

Hi there, I have a 300 line swagger file which is displaying as a blank vscode tab. Any suggestions as to why this may be the case?

Running OSX 10.12.6. The swagger file loads perfectly at editor.swagger.io without any errors.

"swagger: 2.0" is not recognized as a supported version field

When specifying the version field, the viewer doesn't allow 2.0 without quotation:

swagger: 2.0 <-- triggers a "Unable to render this definition"
swagger: "2.0" <-- works

Both are valid Swagger syntax.

Are all dependencies included?

Hi,

I just like to know if all dependencies are included or if my data are being posted to some service and converted to HTML, there.

Best,
Bernhard

Support OAS 3.0.2

To add support for OAS 3.0.2, I've filed a PR to APIDevTools/swagger-parser.

APIDevTools/swagger-parser#102

After the PR is merged/released, I'll file a PR to update dependencies of vs-swagger-viewer. 😉

Extension causes high cpu load

• Issue Type: Performance
• Extension Name: swagger-viewer
• Extension Version: 2.2.2
• OS Version: Darwin x64 18.5.0
• VSCode version: 1.33.1

⚠️ Make sure to attach this file from your home-directory:
⚠️/Users/a564276/Arjun.swagger-viewer-unresponsive.cpuprofile.txt

Find more details here: https://github.com/Microsoft/vscode/wiki/Explain:-extension-causes-high-cpu-load

"Jump to YAML" in swagger UI does not work

Code version 1.21.1, extension version 1.5.0.

I can get previews to load (most of the time...once in a while it's still just a blank white background), but when I click any "Jump to YAML" link in the Swagger UI, the editor doesn't move the cursor to the corresponding definition in the YAML file.

Running the contributed command:'extension.previewSwagger' failed.

I just installed the extension, and I'm getting this error when I try to preview a .yaml file using openapi: 3.0.0
Running the contributed command:'extension.previewSwagger' failed.

VS Code Version 1.25.1 (1.25.1).
Swagger Viewer 2.0.1
MacOS High Sierra Versio 10.13.6

Does not allow for multiple abstracted YAML files

No matter what I try, I can't add a reference to another yaml file, even if it is in the same directory as the main yaml. I'm not sure if this is intended or not, but I'm sure I'm not the only person who is trying to work on large-scale yamls that are being spread out over multiple files.

Thanks!

View preview inside vscode.

Instead of using an external browser, can it open up a new vscode tab and display the result there?

Extension does not respect "swaggerViewer.defaultHost" configuration.

Hi @arjun-g ,

I am developing a tool and was listening on port 9000. When I installed this extension, I discovered a port conflict. I found the swaggerViewer.defaultHost and swaggerViewer.defaultPort configuration settings available. Setting the port to 9010 seems to have resolved the conflict with my other tool.

However, it appears that the listening socket for this extension is listening on 0.0.0.0 despite being told to listen on localhost. I configured it for 127.0.0.1, restarted VS Code, and it's still listening on 0.0.0.0.

Thanks,
@keith-bennett-gbg

Stopped working in version 2.2.1

A white page is displayed when using 2.2.1, but 2.2.0 still works.

swagger: "2.0"
paths:
  /api/trash/{id}/children:
    delete:
      summary: Empty trash
      tags: [trash]
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: Trash entity id
      responses:
        200:
          description: "Success"
        403:
          $ref: "#/responses/AuthorizationFailed"
        404:
          $ref: "#/responses/NotFoundError"
tags:
  - name: trash
    description: Trash APIs
responses:
  AuthorizationFailed:
    description: Authorization failed
  NotFoundError:
    description: Not found

Support running remotely for VS Code Remote Development

Hi, I'm on the VS Code team. We recently released support for Remote Development and I believe that your extension may not work properly when run in a remote workspace

Problem

To make remote development as transparent as possible to users, VS Code distinguishes two classes of extensions:

• UI Extensions: These extensions make contributions to the VS Code user interface and are always run on the user's local machine. UI Extensions cannot directly access files in the workspace, or run scripts/tools installed in that workspace or on the machine. Example UI Extensions include: themes, snippets, language grammars, and keymaps.

• Workspace Extensions: These extensions are run on the same machine as where the workspace is located. When in a local workspace, Workspace Extensions are run on the local machine. When in a remote workspace, Workspace Extensions are run on the remote machine. Workspace Extensions can access files in the workspace to provide rich, multi-file language services, debugger support, or perform complex operations on multiple files in workspace (either themselves or by invoking scripts/tools).

You can find more details about this architecture here.

Your extension is currently running as workspace extension. This means that the server it starts will be run on the remote machine, which in turn means that webview will not be able to access it using localhost since the webview is running on the user's local machine:

Potential Fix

We've introduced a new webview port mapping API that should make it possible for your extension to run remotely with fairly minor modifications.

Please let me know if you have any questions about the issue or the new api. We've also put together a guide to help you test your extension in remote workspaces

The request body disappears when the model is live updated

The request body disappears when the model is live updated.

How to reproduce

Use the following model and preview it in swagger-viewer. Expand the /test method, it contains a form for the requestBody.
Update the model (add a letter in the summary for example). The form has disappeared.

openapi: 3.0.0
info:
  title: test
  version: "1.0.0"

paths:
  /test:
    post:
      summary: Test request body
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                ttl:
                  type: number
                  format: int64
      responses:
        "204":
          description: "ok"

Unable to reference a local yaml file.

Cannot reference an object type specified in another local yaml file.

Example:

Persons:
    type: array
    items:
      $ref: "person.yaml#/Person"

Missing extensio.previewSwagger file

Whenever I download the previewSwagger file is missing :(

Do not collapse the models when they update

Related to #34, I think the models still collapse when they are updated.

Errors do not go away when problem is resolved

When an error is noted and then fixed, the error still populates the live preview. Refreshing causes it to go away, but it isn't working in the live update.

Switch to Swagger Editor 3.x

Hello,

Swagger Editor has released a new major revision, 3.x, which has been rebuilt from the ground up and has better performance and look-and-feel.

I tried to edit it myself, but as I couldn't find any documentation about the edits you've done onto the original Swagger Editor, I didn't have any success.

Thanks in advance, and have a good day !

multipart file upload not working

I have the following OAS3 snippet in my YAML:

  /task:
    post:
      tags:
        - app
      summary: create task
      operationId: createTask
      description: |
        todo
      responses:
        '200':
          description: OK
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                offerNumber: # metadata part
                  description: 'offernumber which has been created upfront'
                  type: string
                  example: '20180042'
                trayImages: # image part
                  type: array
                  items:
                    type: string
                    format: base64
              required:
                - offerNumber
                - trayImages
            encoding:
              trayImages:
                contentType: image/png, image/jpeg
        required: true

When display this on swaggerhub.com, it shows correctly:

When showing the same YAML in VScode with latest Swagger Viewer, it looks like this:

the part with the requestbody and the multipart file upload is totally missing.
When I click on try-it-out it's getting worse. On Swaggerhib I can add multiple files to the request.

A few months ago, I had the same issue on swaggerhub. Now they have fixed it.

Can you please fix this as well?

The site can't be reached when previewing in browser

Hi,

I have a problem with previewing in browser. Once I click "Open"

I get:

Is there a prerequisite I've missed?

Thanks!

Extension causes high cpu load

• Issue Type: Performance
• Extension Name: swagger-viewer
• Extension Version: 2.2.1
• OS Version: Darwin x64 18.5.0
• VSCode version: 1.32.3
  test.txt

TypeError: Failed to fetch

In swagger hub, I do not get the error, however in your preview pane I do:

Is it to do with the XML?

The definition:

---
swagger: "2.0"
info:
  description: "OpenAPI for Abbyy's OCR SDK"
  version: "1.0.0"
  title: "AbbyyOCR"
  contact:
    email: "[email protected]"
host: "cloud.ocrsdk.com"
basePath: "/"
schemes:
- "https"
securityDefinitions:
  basicAuth:
    type: "basic"
security:
- basicAuth: []
paths:
  /getApplicationInfo:
    get:
      summary: "Gets information about the account"
      description: "This method allows you to receive information about the application type, its current balance and expiration date. You may find it helpful for keeping the usage records."
      operationId: "GetApplicationInfo"
      produces:
       - "application/xml"
      parameters: []
      responses:
        200:
          description: "Successful method call."
          schema:
            type: array
            items:
             properties:
              name:
               type: string
              pages:
               type: integer
              fields:
               type: integer
              expires:
               type: string
              type:
               type: string
        403:
          description: "The call to this method is disabled in your application settings."
  /processImage:
    post:
      summary: "Passes task for processing"
      description: "Loads the image, creates a processing task for the image with the specified parameters, and passes the task for processing."
      operationId: "ProcessImage"
      consumes:
      - "multipart/form-data"
      produces:
      - "application/xml"
      parameters:
      - name: "File"
        in: "formData"
        description: "The file to process."
        required: false
        type: "file"
      - name: "language"
        in: "query"
        description: "Recognition language of the document."
        required: false
        type: "string"
        default: "English"
      - name: "exportFormat"
        in: "query"
        description: "Specifies the export format."
        required: false
        type: "string"
        default: "pdfTextAndImages"
      responses:
        200:
          description: "Successful method call."
        450:
          description: "Incorrect parameters have been passed."
        550:
          description: "An internal program error occurred while processing the image."
        551:
          description: "An error occurred on the server side."

definitions: {}

Thanks

Preview does not render when chained $refs

In the current directory we have a api.yaml and a common-schemas.yaml file. In the api.yaml file there is a ref to a definition.yaml file in a subdirectory.

-api.yaml
-common-schemas.yaml
-customactions/definition.yaml

The api.yaml file has a reference to a path in the customactions/definitions.yaml file.

paths:
/customactions:
$ref: "customactions/definition.yaml#/paths/~1customactions"

The customactions definition.yaml file has in a schema section a reference to a file in the parent directory.

$ref: "../common-schemas.yaml#/components/schemas/hateoasLink"

If you preview the definiton.yaml file by itself the doc renders properly with the $ref: "../common-schemas.yaml#/components/schemas/hateoasLink" being resolved correctly. However if you try to render the parent api.yaml file it does not include the definitions from the definition.yaml file. There is an error on that page that says:

Invalid $ref pointer "components,schemas,hateoasLinks". Pointers must begin with "#/"

If I use swagger-ui to view the same code, the api.yaml doc renders correctly.

Swagger files with *.yml extension doesn't work

swagger.yaml works, swagger.yml — just white screen. See screenshots below:

Blank/white screen with *.json; *.yaml works fine

Hi,

As of the latest update, I've found none of my *.json swagger files will preview in the tab/browser, whereas the exact same version in *.yaml works fine.

I've tested the json version of my swagger files on the swagger.io site and they render fine. Even exporting those same json files as yaml and previewing in the plugin in VSC also works fine. It just seems there is something wrong/different with the JSON rendering.

Would love some suggestions on how to correct this -- i find this plugin to be an incredibly useful tool and saves a huge amount of time.

$ref path handling problematic

I have the following reference in my YAML file

          schema:
            $ref: '../schema/customer-address-v1.yaml#/components/schemas/Address'

But the swagger viewer thinks that this is an improper path, and it is looking for the referenced file here

  Error opening file "users/alex/sites/work/schema/customer-address-v1.yaml"

It should be looking in

users/alex/sites/work/{project}/customer/profile/schema/customer-address-v1.yaml

Other applications like swagger-cli correctly use the relative path reference in my YAML file, but swagger-viewer does not (which renders swagger viewer problematic)

This is on a Mac, in case that is significant.

I note that internally your extension uses the open source swagger-parser, and when I use that (or swagger-cli, which uses it), then there is no problem with the reference handling.

This still requires active internet connection right?

I downloaded this because I assumed this is an offline tool so that I can work on my swagger API offline. But it seems to be connecting to swagger.io to preview the files... am I right?

If that is the case it does not add any value... I might as well you editor.swagger.io directly from Chrome.

Swagger preview changes versions

Hi,
I have used the online swagger editor which allows you chose between the new and old versions. I recently installed the vscode plugin which has been really useful. I've noticed that the preview appears to change between the versions of the editor. Usually when I first open vscode it will show the preview is in the latest version, then after some changes it will change to the older version. I can't quite pick out anything specifically that has triggered this behavior. Is there a way to force a specific version of the preview?

Regards

Option to disable "Preview Done" notification

While I love this extension, the "PREVIEW DONE" notification is quite obnoxious and annoying.
Especially since it has a red cross hinting that there was an error, being written in all caps and me having to click it to go away.

Therefore, I think there should be an option to turn this notification off.

Thanks a lot!

Work with split file

Works with split files?
($ref use)

Upgrade to VS Code's webview API

Hi, I'm on the VS Code team. I noticed that your extension uses the vscode.previewHtml command which is deprecated and which we are actively working to remove: microsoft/vscode#62630

We've developed a webview API that provides a much better developer experience and offers a number of important security and compatibility benefits over previewHtml. We cannot fix previewHtml without breaking backwards compatibility, and have instead opted to remove it.

To ensure that your extension continues to work properly in VS Code, please try upgrading to use the new Webview API. You can find documentation on the API usage here. Let me know if you have any questions or concerns about this migration

External refs not working

If you have ref like this $ref: "common.yaml#/definitions/StatusMessage" you will get this error message:

Resolver error at paths./authenticate.post.responses.401.schema.$ref
Could not resolve reference because of: Tried to resolve a relative URL, without having a basePath. path: 'common.yaml' basePath: 'undefined'
Resolver error at paths./authenticate.post.responses.default.$ref
Could not resolve reference because of: Tried to resolve a relative URL, without having a basePath. path: 'common.yaml' basePath: 'undefined'

Ability to export static HTML files

@arjun-g, thanks for your hard work with this, it's a very good plugin.

Is there a way to save the preview as static HTML files that I can then publish? I really like the look and feel compared to using, say, swagger-ui.

Publish Version 1.7.0

The fix for JSON parsing has not been published to the VS Code Extensions Marketplace.

https://marketplace.visualstudio.com/items?itemName=Arjun.swagger-viewer

Extension causes high cpu load

• Issue Type: Performance
• Extension Name: swagger-viewer
• Extension Version: 2.2.2
• OS Version: Windows_NT x64 10.0.17763
• VSCode version: 1.33.1

⚠️ Make sure to attach this file from your home-directory:
⚠️C:\Users\softdib\Arjun.swagger-viewer-unresponsive.cpuprofile.txt
Arjun.swagger-viewer-unresponsive.cpuprofile.txt

Find more details here: https://github.com/Microsoft/vscode/wiki/Explain:-extension-causes-high-cpu-load

how to change the default port 9000?

OAuth redirect not working

The redirect from OAuth does redirect to the swagger-ui, but keeps haning when returning from the provider, not redirecting to swagger-ui.
https://localhost:9000/oauth2-redirect.html#/access_token%3DeXXXXX

I use "swaggerViewer.previewInBrowser": true, as the Swagger-ui will not display the login screen in VS Code.

I can render the same contract and login using OAuth using 'swagger-ui-express'.

Synchronize to Swagger-Editor 3.4.0 (newest)

Is there any chance to synchronize this addon with newest Swagger?

Read swagger object as part of bigger json

It would be useful to be able to read the swagger part of a Cloudformation template, when declaring an AWS API Gateway.

The syntax is the same, and is placed under a "Body" tag in the config (see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body).

Possible solution would be to parse the entire json for any swagger/openAPI version field (swagger: "2.0" or openapi 3.0.0) and use the containing object as input for this plugin. Support for multiple apis in same Cloudformation Template is probably not needed, since one would probably use separate files for more complex projects like this.

Extension causes high cpu load

• Issue Type: Performance
• Extension Name: swagger-viewer
• Extension Version: 2.2.1
• OS Version: Darwin x64 18.5.0
• VSCode version: 1.33.1

⚠️ Make sure to attach this file from your home-directory:
⚠️/Users/darwin/Arjun.swagger-viewer-unresponsive.cpuprofile.txt

Find more details here: https://github.com/Microsoft/vscode/wiki/Explain:-extension-causes-high-cpu-load

Validator is too aggressive

The swagger validator attempts to validate any json file with a top level key of swagger even if it isn't a swagger file. This leads to problems popping up in the problem list when they shouldn't.