Chapter 3. Update To ActiveDocs 2.0
The details of this section are for reference only. This option is no longer supported and you should consider migrating away from this configuration at the earliest opportunity.
By the end of this tutorial, you will know what changes you need to make to your ActiveDocs configuration to successfully upgrade to version 2.0.
For instructions applicable to the configuration of ActiveDocs 2.0, you can refer to Adding Specifications to 3scale. 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.
If your ActiveDocs spec is still in version 1.0, then please first convert it to version 1.2.
3.1. Step 1: Apply the appropriate naming convention to your specification
Navigate to the API
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.
3.2. 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.
3.3. 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" %}
<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>3.4. Step 4: Test your API using ActiveDocs 1.2
Remember to enable Liquid tags on your CMS configuration page.
- Finally, while in the preview mode, close the right-hand vertical sidebar to see ActiveDocs 2.0.
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.
