Dynamic documentation for the 3scale Developer Portal

README.md

Dynamic documentation for the 3scale Developer Portal

Goal

Generate a dynamic list of the exposed services on the 3scale Developer Portal.

How to install

Replace your built-in "Documentation" page (/docs) in the 3scale CMS with the attached content.

Limitations

Currently, this module expects that Services and ActiveDocs objects will have the same system_name (in order to match a service with an ActiveDocs).

documentation.html

{% cdn_asset /swagger-ui/2.2.10/swagger-ui.js %}
{% cdn_asset /swagger-ui/2.2.10/swagger-ui.css %}

{% include 'shared/swagger_ui' %}

<div class="api-list-container" style="display: none;">
  <h1>API Catalog</h1>
  <p>List of all available APIs:</p>
  <ul class="api-list">
  </ul>
</div>

<script type="text/javascript">
  var services = {
  {% assign items = provider.services |map: "system_name" %}
  {% for system_name in items %}
  {% if provider.api_specs[system_name] %}
  "{{ system_name }}": {
    name: "{{ provider.services[system_name].name|url_encode }}",
    url: "{{ provider.api_specs[system_name].url }}",
    description: "{{ provider.services[system_name].description|url_encode }}" 
  },
  {% endif %}
  {% endfor %}
  };

  $( document ).ready(function() {
    var searchParams = new URLSearchParams(window.parent.location.search) ;
    if (searchParams.has("api")) {
      var api = searchParams.get("api");
      $(".api-list-container").css("display", "none");
      window.swaggerUi.options['url'] = services[api].url;
      window.swaggerUi.load();
    } else {
      $(".api-list-container").css("display", "block");
      var system_names = Object.keys(services).sort();
      for (var i = 0; i < system_names.length; i++) { 
        var name = system_names[i]; // system_name
        if (services[system_names[i]].name != null) { // if present, name is a better option
          name = decodeURIComponent(services[system_names[i]].name.replace(/\+/g, '%20')) + ": " + decodeURIComponent(services[system_names[i]].description.replace(/\+/g, '%20'));
        }
        $("<a>", { "href": "?api=" + system_names[i], text: name }).appendTo($("<li>").appendTo($(".api-list")));
      }
    }
  });

</script>