Update To ActiveDocs 2.0

SaaS On-premises 2.0
By the end of this tutorial, you’ll know what changes you need to make to your ActiveDocs configuration to successfully upgrade to version 2.0.

Most of the instructions applicable to configure ActiveDocs 2.0 are shown on the pages Configure ActiveDocs/Swagger and ActiveDocs/Swagger Specification. Detailed spec-related differences can be found on the official Swagger 1.2 to 2.0 Migration Guide. This article simply documents the extra steps to upgrade to ActiveDocs 2.0.

Note

If your ActiveDocs spec is still in version 1.0, then please first convert it to version 1.2.

Step 1: Apply the appropriate naming convention to your specification

Navigate to the API > ActiveDocs tab in your Admin Portal. This will lead you to the list of your service specs. You should have already added a service spec (see step 2 in Configure ActiveDocs/Swagger.

Naming your specification

You should apply appropriate names to achieve the desired effect in your Developer Portal – the heading of your ActiveDocs API listing will appear as "System name: Description". You may need to recreate the spec again simply by copying the JSON spec and other fields, as the system name is read-only.

Step 2: Modify service spec

The specification for ActiveDocs 2.0 has some important changes to those for version as compared to version 1.2. See the Swagger 1.2 to 2.0 Migration Guide for detailed information. The most important changes are:

  • the "swaggerVersion": "1.2" root element is now "swagger": "2.0" and it is a required field.
  • The "info" object becomes required.
  • The "apiVersion": "1.0" becomes required and is now part of the "info" object: "info": { "version": "1.0", ... }
  • The description in the "info" object becomes non-mandatory.
  • The license name field becomes required if "license" object is present.
  • The "basePath": "https://example.com/api" field is split into three fields: "host": "example.com", "basePath": "/api" and "schemes": [ "http" ]. None of these fields is mandatory.

Step 3: Add the Javascript and HTML content to your CMS page

Add the following code snippet to your CMS page, where SERVICE_NAME should be the system name of the service spec.

<h1>Documentation</h1>
<p>Use our live documentation to learn about Echo API </p>
{% active_docs version: "2.0" services: "SERVICE_NAME" %}
<script type="text/javascript">
  $(function () {
    {% comment %}
    // you have access to swaggerUi.options object to customize its behaviour
    // such as setting a different docExpansion mode
    window.swaggerUi.options['docExpansion'] = 'none';
    // or even getting the swagger specification loaded from a different url
    window.swaggerUi.options['url'] = "http://petstore.swagger.io/v2/swagger.json";
    {% endcomment %}
  window.swaggerUi.load();
});

</script>

If you want to include multiple Swagger specs on one page, you may use this customized snippet:


{% active_docs version: "2.0" services: "oauth" %}
<div class="swagger-section">
  <div id="another-swagger-ui-container" class="swagger-ui-wrap"></div>
</div>
<script type="text/javascript">
  $(function () {
    window.swaggerUi.load(); // <-- loads first swagger-ui
     // do second swagger-ui
     var url = "/swagger/spec/sentiment.json";
    window.anotherSwaggerUi = new SwaggerUi({
      url: url,
      dom_id: "another-swagger-ui-container",
      supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
      onComplete: function(swaggerApi, swaggerUi) {
        $('#another-swagger-ui-container pre code').each(function(i, e) {hljs.highlightBlock(e)});
      },
      onFailure: function(data) {
        log("Unable to Load Sentiment-SwaggerUI");
      },
      docExpansion: "list",
      transport: function(httpClient, obj) {
        log("[swagger-ui]>>> custom transport.");
        return ApiDocsProxy.execute(httpClient, obj);
      }
    });
     window.anotherSwaggerUi.load();
   });
</script>

Step 4: Test your API using ActiveDocs 1.2

  • Remember to enable Liquid tags on your CMS configuration page.
    Enable Liquid tags
  • Finally, while in the preview mode, close the right-hand vertical sidebar to see ActiveDocs 2.0.

Note

The new styles are compliant with the newer Swagger spec (2.0). If you would like to change the look and feel, you would have to override the styles. Since the CSS for Swagger is included together with the HTML, you would have to define the styles with a higher specificity or with the !important tag.