Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

3Scale Developer Portal Docs Per Application

DZone's Guide to

3Scale Developer Portal Docs Per Application

Using this open source platform, we to create a more effective version of your API documentation, allowing devs to only see that docs that are relevant to their work.

· Integration Zone ·
Free Resource

Download Microservices for Java Developers: A hands-on introduction to frameworks and containers. Brought to you in partnership with Red Hat.

Having Swagger Documentation in any developer portal is very important for developers to know how to use APIs. However, not all developers may be using the same applications. How can you make it so developers only see the docs relevant to them? Luckily some JavaScript magic can make this possible for the 3Scale developer portal.

First, you will want to make sure you have Swagger JSON defined on a per-application basis. For example, take these 3 JSON files and ensure they are published somewhere on the web with no header, footer, etc.

An easy way to do this is to navigate to the Developer Portal tab in your 3Scale Admin Console and select “New Page.” Name your page and give it a path like /<applicationName>.json. Also, ensure no layout is selected. Then save and publish the page. Note: You may have to go to the drafts page to publish the page. Do this for all applications. You can also host these on any external site if you wish.

Once all the swagger JSON pages are created you simply need to use JavaScript to find out what applications a user has, and then display the Swagger docs for each. From the Developer Portal configuration page inside the 3Scale admin console, edit the Documents page to be similar to what is shown below:

{ % active_docs version: "2.0" %} 
{ % for applicaiton in current_account.aplications %} 
  <div class = "swagger-section">
    <div id = "another-swagger-ui-{{application.name}}" class = "swagger-ui-wrap"></div> 
  </div>
    <script type = "text/javascript" >
   	 $(function() {
        	var dom_id = "another-swagger-ui-{{ application.name }}";
        	var url = "https ://<yourAccount>.3scale.net/{{ application.name }}.json";
      	    window.anotherSwaggerUi = new SwaggerUi({
            	url: url,
            	dom_id: dom_id,
            	supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
            	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>
 
{% endfor %} 

Important Notes:

  • The active docs tag must be present to ensure the swagger libraries are loaded. However, a service name does not need to be specified in the tag.
  • A div with a different ID must be defined for each application. If this is not done only the last application’s Swagger UI will load since it will get continually overwritten.
  • You can use any layout you want with this code.
  • Adjust the logs to your liking.

Download Building Reactive Microservices in Java: Asynchronous and Event-Based Application Design. Brought to you in partnership with Red Hat

Topics:
integration ,developer documentation ,api documentation ,javascript ,json

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}