Generating Code and Documentation

<< Click to Display Table of Contents >>

Navigation:  »No topics above this level«

Generating Code and Documentation

Previous pageReturn to chapter overviewNext page

Typically, you will evolve your API design in an iterative process using the Mock Service (design > try > design > try etc.). Once it seems to be OK from the outside, from the point of view of clients and other services that will use it, you will be ready to implement. The next step is to generate code and documentation.

RepreZen™ API Studio has an extensible, template-based code generator.  Multiple predefined code generation templates are included, along with documentation and diagram generators. The following are added by default:

GeneratingCode_01

You can now run the Diagram generator from the toolbar:
 
GeneratingCode_02

When the task completes you'll see a notification dialog. Close this and then look for the generated output under the gentargets directory:
 
GeneratingCode_03

To view the generated diagram right-click the TaxBlaster_diagram.html file and select Open With > Web Browser.

Things to try next

Experiment by adding further generation targets to the project. See what each one produces in terms of outputs. To add a new GenTarget:

1.Click the button in the toolbar:
GeneratingCode_04
2.Select a type from the dropdown menu, for instance RAML:
GeneratingCode_05
3.If the Next button is enabled press it and keep going to complete the generator chain, otherwise press Finish.
4.A gen file will open in an editor which describes the GenTarget you have just added: the template used; the input rapid model; the output directory and optional custom parameters:
GeneratingCode_06

Also try playing around with different ways of running the generation targets. Use the toolbar dropdown menu to run specific gen targets or all of the gen targets in the project. You can also run a specific gen target by right-clicking the gen file or parent directory and selecting Generate...

The Generated Documentation

The generated documentation uses Bootstrap for formatting and interactive controls.  You can plug in any standard or custom Bootstrap theme by changing the CSS stylesheet reference in the generated HTML file.
The documentation is pure HTML, CSS and JavaScript.
You can publish the documentation for end users to view in any modern browser.
The layout of the documentation page is responsive to changes in window size:
oIf you maximize, restore, or re-size the Documentation view or browser window, you'll see some changes in the layout.
oMost importantly, the navigation controls will be placed to the left of the main content if there is sufficient width available.  Otherwise, the navigation controls are in a drop-down menu on the right side of the header.

The Generated Diagram

As with the documentation, the diagram is implemented using standard web technologies, so you can deploy the diagram and view it in any modern browser, complete with the interactive expand/collapse functionality.

Other built-in Generators

The following are some of the other generators built-in to RepreZen API Studio:

XML Schema - A standard XSD schema which describes an XML format for resource representations.  The generated schema is located in the RepreZen-generated/wadl subfolder.  It uses a hyperlink format specified in the Atom Syndication Format, and therefore the schema has a dependency on atom.xsd, which is copied into the same folder.
JSON Schema - A standard JSON schema which describes a JSON representation format.
WADL - A description of the API using the Web Application Description Language.  WADL is a W3C Submission, not an official Recommendation.  But it is still useful as an interchange format for API descriptions.
JAX-RS Scaffolding - Java code with JAXB and JAX-RS annotations, which can be used as a starting point for a service implementation.

This provides a starting point for your own service implementation now that this has been designed and tried out.

Build your own Generator

RepreZen API Studio makes it easy to add your own code generation templates which are written using the Xtend language. For more information on this and other subjects please see our YouTube-social-icon_red_24px Youtube Channel.

Copyright © 2016 ModelSolv, Inc.  All rights reserved. RepreZen and RAPID-ML are trademarks of ModelSolv, Inc. Swagger is a registered trademark of SmartBear Software, Inc. RepreZen API Studio is not associated with nor endorsed by SmartBear Software, Inc.