Publishing RESTful Web Service Documentation

Documentation home

 

Publishing RESTful Web Service Documentation. 1

Editing Swagger Documentation. 2

Application. 3

Endpoints 4

Request Documentation. 5

Path Parameters 5

Request Body. 6

Parameters 7

Request Headers 8

Response Documentation. 8

Response Information. 9

Response Headers 9

Definitions 10

View Published Documentation. 13

 

See also:

Publishing RESTful Web Service Documentation

 

Verj.io uses the Swagger framework to publish RESTful Web Service as JSON or YAML documents. Swagger is a framework that generates a simple representation of the RESTful service API. Swagger provides descriptive documentation about your REST API. Swagger UI tools also provide an interactive test framework to the REST API.

 

To generate either JSON or YAML documents:

 

Swagger JSON URI

 

http://<domain-name>:<port>/<web-app>/api/<service_name>/swagger.json

 

Swagger YAML URI

 

http://<domain-name>:<port>/<web-app>/api/<service_name>/swagger.yaml

 

It is possible to copy and paste either the JSON or YAML documents or load the URL above into any Swagger reader to view the documentation and interactively test the API. Swagger tools make it possible to create many client API’s, e.g JavaScript or Java. Click here for more information about generating client interface framework.

 

The Verj.io server contains an integrated Swagger UI to view and test the published Swagger documentation. The JSON document is converted to a web page that displays the documentation about the RESTful Web Service and the associated endpoints. The documentation can be accessed through the designer by clicking the  icon in the RESTful Web Service toolbar or directly by entering the URL into a browser.

 

The external URL to view the published documentation is as follows:

 

http://<domain-name>:<port>/<web-app>/ebasePublishRest.eb?serviceName=<service-name>

 

See View Published Documentation for more information.

 

 

Editing Swagger Documentation

 

Open the RESTful Web Service that you would like to edit the documentation. Click on the  icon in the toolbar to open the sub menu then click on the  located on the dropdown to open the documentation dialog.

 

 

The left hand panel displays a tree structure for editing various sections of the documentation. Click on the appropriate node to show documentation fields in the right hand panel for:

 

Application: Overview of the RESTful Web Service.

Endpoints: This contains list of endpoints contained within the RESTful Web Service.

Request: Documentation related to the incoming request

Response: Documentation related to the outgoing response.

Definitions: List of structures to create individual object types or full JSON/XML structures.

 

Application

 

The application panel documents the overview of the RESTful Web Service and consists of the following fields:

 

 

 

 

Title: This is required and contains the title of the application.

Description: A short description of the RESTful Web Service. HTML and GFM syntax can be used for rich text representation

Terms of service: The Terms of Service for the API.

Version:  This is required and provides the version of the application API.

 

External Documentation: Additional external documentation for this application.

Description: A short description of the target documentation. HTML and GFM syntax can be used for rich text representation.

Link:  Link to an external website

 

Supported Mime Types:

Consumes: List of the MIME types that the RESTful Web Service accepts. This is global to all endpoints but can be overridden on specific endpoints.

Produces: List of the MIME types that the RESTful Web Service returns. This is global to all endpoints but can be overridden on specific endpoints.

 

The figure below shows the Application information when viewed in the external browser. Click the  icon to view the documentation to view the published documentation.

 

Endpoints

 

Click on the endpoint name to edit the documentation for the specific endpoint.

 

 

Name: Read only field that displays the name of the endpoint.

Path: Read only field that displays the path for the endpoint URI.

Supported Methods: Read only field that displays the HTTP methods for the endpoint.

Consumes: List of the MIME types that the endpoint accepts. This value overrides the global consumes property.

Produces: List of the MIME types that the endpoint returns. This value overrides the global produces property.

Summary: A short summary of the endpoint functionality. For maximum readability in the swagger-ui this field SHOULD be less than 120 characters.

Implementation Notes:  A verbose explanation of the endpoint functionality. HTML and GFM syntax can be used for rich text representation.

 

Request Documentation

 

Click on the  Request node to edit the documentation for the incoming request.

 

Path Parameters

 

The path parameters table is automatically populated with the path parameters that are in the endpoint URI. Path parameters are enclosed within {}, e.g /customer/{customerId}.

 

It is not possible to add additional parameters to the path parameters table.

 

 

 

Name: This is a read only column and is the name of the parameter extracted from the endpoint URI.

Description: A short description about the parameter. This could contain examples of use. GFM syntax can be used for rich text representation.

Data Type: This is required. The value MUST be one of "string", "number", "integer", "boolean". The default data type is a string.

Default Value: Specify a default value to populate the parameters field in the documentation.

 

Request Body

 

Add documentation for the request body. The request body is only applicable for HTTP POST and PUT requests.

 

 

 

Name: Enter a one word description of the request type.

Description:   short description about the parameter. This could contain examples of use. GFM syntax can be used for rich text representation.

Definition: Select the definition reference for the request body.

 

Parameters

 

The parameters table contains a list of the Query or Post parameters for the request. Parameters are not configurable from the RESTful Web Service Editor but should be added to the documentation if they are required at runtime.

 

 

Click the  icon to add a new parameter.

Click the  icon to delete the selected parameter.

Click the  icon to move the parameter up the list.

Click the  icon to move the parameter down the list.

 

 

Name: This is required. Enter a name for the parameter.

Description: A short description about the parameter. This could contain examples of use. GFM syntax can be used for rich text representation.

Data Type: This is required. The value MUST be one of "string", "number", "integer", "boolean". The default data type is a string.

Default Value: Specify a default value to populate the parameters field in the documentation.

Required: When selected this prompts the user that the field must be entered.

 

 

Request Headers

 

The headers table contains a list of the HTTP headers for the request. Request headers are not configurable from the RESTful Web Service Editor but should be added to the documentation if they are required at runtime.

 

 

Click the  icon to add a new request header.

Click the  icon to delete the selected request header.

Click the  icon to move the request header up the list.

Click the  icon to move the request header down the list.

 

 

Name: This is required. Enter a name for the request header.

Description: A short description about the request header. This could contain examples of use. GFM syntax can be used for rich text representation.

Data Type: This is required. The value MUST be one of "string", "number", "integer", "boolean". The default data type is a string.

Default Value: Specify a default value to populate the request headers field in the documentation.

Required: When selected this prompts the user that the field must be entered.

 

 

Response Documentation

 

Click on the  Response node to edit the documentation for the outgoing response.

 

 

Click the  icon to add a new response.

Click the  icon to delete the selected response.

Click the  icon to move the response up the list.

Click the  icon to move the response down the list.

 

Double click a response to edit the response documentation.

 

When adding or editing a HTTP response a dialog is opened with two tabs:

 

 

Response Information

 

Enter the documentation for the response.

 

 

Response Status: Enter the response status code for the response. If no status is entered the response is displayed as a default response. This indicates that this is the default response for all statuses; this excludes the others responses specified.

Description: Enter a description about the response. This could contain examples of use. GFM syntax can be used for rich text representation.

Definition: Select the definition reference for the response body. Response bodies are only applicable to HTTP GET, POST and PUT responses.

 

Response Headers

 

Enter the documentation for the response headers.

 

 

Click the  icon to add a new response header.

Click the  icon to delete the selected response header.

Click the  icon to move the response header up the list.

Click the  icon to move the response header down the list.

 

Name: This is required. Enter a name for the response header.

Description: A short description about the response header. This could contain examples of use. GFM syntax can be used for rich text representation.

Data type: The value can be one of "string", "number", "integer", "boolean". The default data type is a string.

 

Definitions

 

A definition contains a tree structure containing data nodes. A definition is used to organize and structure objects that define a structure that represents a JSON or XML structure. JSON structures can have multiple data nodes at the root of the definition node where as XML structures can only contain one root node.

 

The definitions are used when defining the incoming Request Body and the outgoing Response Body of the RESTful Web Service. A data node where its type is set to ‘object’ can reference another definition.

 

Click on the  icon to show the definitions. This opens the Definitions View Panel. The Definitions View Panel shows a list of the definitions in a tree. To the right of the tree is the Data Node Properties panel to edit the individual data nodes.

 

 

The three icons used in the Definitions View are:

 

 - A single Definition structure.

* - indicates a basic type, JSON object or an XML element

* - indicates and XML attribute and is only used for XML only structures.

 

Definition

 

To add a new definition - Click the add toolbar icon  and select  Add definition from the drop down menu.

To rename a definition - Select the definition and click the rename toolbar icon . Enter a new name in the definition name dialog box.

To delete a definition - Select the definition and click the delete toolbar icon .

 

Data nodes

 

To add a new data node - Select the parent Data node of the new node.   Click the add toolbar icon  and select  Add node from the drop down menu.  The new node will be selected and its properties can be edited in the data node properties panel.

To delete an data node - Select the node and click the delete toolbar icon .  This node, all of its sub structure and attached fields will be deleted.

To rearrange sibling nodes – Use the move down  and move up  buttons to change the order of adjacent XML nodes.  XML Attributes will always appear before elements.

 

The location of data nodes can also be changed using drag and drop functionality.

 

Data Node properties panel

The Data Node Properties panel shows the properties of the selected Data node.  All properties are editable.

 

 

Name – data node name of the selected node.

Title – Short description of the data node

Description - A short description about the data node. This could contain examples of use. GFM syntax can be used for rich text representation.

Type - The drop down lists some or the common data types.  By selecting ‘object’ in the type field enables the Definition field below.

Definition - Select the definition for the ‘object’ type.

Required – By checking the required checkbox indicates that the value must be entered.

XML Attributes – The following attributes are specific to XML structures only.

Namespace – The namespace for the XML element

Node Type - Select either element or attribute.

 

Data Node Data Types

The data nodes type can be set to either: array, boolean, decimal, double, float, integer, long, object or string. If a data node type is set to <none> then the node can contain children to create a tree structure used in JSON and XML structures. 

 

If the data node is set to ‘array’ then the node can contain one child and this child must have a data type set.


View Published Documentation

 

Open the RESTful Web Service and click on the  icon in the toolbar to open the sub menu then click on the  icon to view the documentation to view the published documentation. This will launch an external browser window. The RESTful Web Service must be saved if modified to view any documentation changes.

 

The URL to the published documentation is formatted as:

 

http://<domain-name>:<port>/<web-app>/ebasePublishRest.eb?serviceName=<service-name>

 

The figure below shows the published documentation:

 

 

 

 

Viewing and Testing Endpoints

 

Click the endpoint name to expand the information on the endpoint. To test the endpoint - enter information into the appropriate fields and click the  button.

 

The figure below shows an endpoint configured as a HTTP GET and returns a customer from a supplied customer id path parameter.

 

 

The figure below shows the response after filling in the form from the figure above and clicking the  button.

 

 

 

The figure below shows an endpoint configured as a HTTP POST that accepts a customer JSON object and returns a newly create customer id.