Adding SwaggerUI to your project

You can use the OpenAPI specification to configure Swagger UI, which is an interactive documentation tool.

Installing Swagger UI

The following sections show how to install Swagger UI for various languages.

Installation for Node.js

This section assumes that you have a working nodejs application, with an OpenAPI configuration file openapi.yaml. If you don't have one, you can start with our sample app.

  1. Install the Swagger UI and Swagger Tools packages:

    npm install swagger-ui
    npm install swagger-tools
    npm install yamljs
    
  2. Add the following requirements to the top of your main server file:

    var swaggerTools = require('swagger-tools');
    var YAML = require('yamljs');
    var swaggerDoc = YAML.load('openapi.yaml');
    
  3. Add the following to your app initialize the Swagger UI:

    swaggerTools.initializeMiddleware(swaggerDoc, function (middleware) {
      // Serve the Swagger documents and Swagger UI
      app.use(middleware.swaggerUi());
    });
    
  4. Start your app and browse to http://<yourapp>/docs to use Swagger UI to interact with your API.

Installation for other languages and frameworks

To install Swagger UI for languages other than Node.js:

  1. Clone the git repository into a temporary directory:

    mkdir tmp
    cd tmp
    git clone https://github.com/swagger-api/swagger-ui.git
    
  2. Copy the dist folder from the local copy of the git repository into a folder in your project. In this example it is called docs:

    cd swagger-ui
    cp -R dist /yourproject/docs
    
  3. Make sure that the name in the host property in the openapi.yaml file is the fully qualified domain name (FQDN) of your API.

  4. To serve the UI, modify the app's app.yaml to specify handler locations:

    handlers:
      - url: /docs
        static_files: docs/index.html
        upload: docs/index.html
      - url: /docs/(.*)
        static_files: docs/\1
        upload: docs/.
    
  5. Modify /yourproject/docs/index.html, changing the url attribute:

    url = "../api-docs";
    

    This directs the Swagger UI to retrieve your OpenApi spec from this URL. Add a handler for this path which reads your openapi.yaml and serves it as json.

  6. Deploy your app and browse to http://<yourapp>/docs to use Swagger UI to interact with your API.

Send feedback about...

Cloud Endpoints with OpenAPI