Generating Code and Documentation
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:
You can now run the Diagram generator from the toolbar:
When the task completes you'll see a notification dialog. Close this and then look for the generated output under the gentargets directory:
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:|
|2.||Select a type from the dropdown menu, for instance RAML:|
|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:|
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.|
|•||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:|
|o||If you maximize, restore, or re-size the Documentation view or browser window, you'll see some changes in the layout.|
|o||Most 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
|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.|