REST Documentation [ IRIS ]

This project is a developement tool that aims to assist you to visually analyzing the flow of your REST API endpoints, based on a ObjectScript class reference;

With it is possible to add annotations that document your API to add more information when generating the documentation.

Prerequisites

Make sure you have git and Docker desktop installed.

Installation

Clone/git pull the repo into any local directory

$ git clone https://github.com/Davi-Massaru/IRIS_REST_Documentation.git

Open the terminal in this directory and run:

$ docker-compose build

Run the IRIS container with your project:

$ docker-compose up -d

Getting Started

In the folder src/restApi there is an example of an ObjectScript RestApi, look for restApi.dispath.cls

Note:

${host} : your host’s server
${port} : your application’s port (the same one you use access the Management Portal)

try to access the link

http://${host}:${port}/csp/${namespace}/RestDocumentation.View.DocumentationRestView.cls?CLASSNAME=restApi.dispath.cls

If you are using VsCode and have the InterSystems ObjectScript Extension Pack extension, access restApi.dispath.cls, click on the extension’s dedicated button and select RestDocumentation.

For this to work, make sure that your settings.json in the .vscode folder looks like this:

    "objectscript.conn" :{
      "ns": "USER",
      "username": "_SYSTEM",
      "password": "SYS",
      "links": {
        "RestDocumentation": "http://${host}:${port}/csp/${namespace}/RestDocumentation.View.DocumentationRestView.cls?CLASSNAME=${classname}"
      }

If necessary, login with the _SYSTEM or other user.
And now you have an UI visualization of the rest class Api.dispatch with its routes and Maps generated described in the XData UrlMap

XData UrlMap
{
    <Routes>
        <Map Prefix="/api/v1*" Forward="restApi.v1.api"/>
        <Map Prefix="/api/v2*" Forward="restApi.v2.api"/>
        <Route Url="/ping/" Method="POST" Call="PingPost" />
        <Route Url="/ping/" Method="GET" Call="Ping" />
        <Route Url="/ping/test/get/:myParameter/DocumentationMethodSample" Method="GET" Call="DocumentationMethodSample" Cors="true"/>
    </Routes>
}

Compare to

Document your Rest API

ROUTES:

Url : It is provided by the XData UrlMap < Route Url = “” > described in the class
Method : It is provided by the XData UrlMap < Route Method = “” > described in the class
Call : It is provided by XData UrlMap < Route Call = “” > described in the class
Cors : It is provided by XData UrlMap < Route Cors = “” > described in the class
Description : It is provided by Method description in the classmethod called by < Route Call=”” >
ResponseBody : It is provided by Annotation @ResponseBody( ) described in the Method description
RequestBody : It is provided by Annotation @RequestBody( ) described in the Method description
ContentType : It is provided by Annotation @ContentType( ) described in the Method description
ParameterQuery < LIST > : It is provided by Annotation @ParameterQuery( ) described in the Method description you can enter several @ParameterQuery( )

Maps:

Prefix : It is provided by the XData UrlMap < Map Prefix = “” > described in the class;
Forward : It is provided by the XData UrlMap < Map Forward = “” > described in the class;
Description : It is provided by the Description class described in the class called in Forward;

Annotations

The annotations are defined in the description of the method and are used to add additional information to the RestAPI documentation;

Class restApi.api Extends %CSP.REST
{

/// Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. 
/// It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.
/// 
/// @ResponseBody(restApi.Model.Sample)
/// @RequestBody(restApi.Model.Company)
/// @ContentType(application/json)
/// @ParameterQuery(color,blue|green|red)
/// @ParameterQuery(name,string)
/// @ParameterQuery(company,string)
ClassMethod DocumentationMethodSample() As %Status
{
    Set sc = $$$OK
    // do something
    Return sc
}

XData UrlMap
{
<Routes>
    < Route Url="/ping/get/:myParameter/DocumentationMethodSample" Method="GET" Call="DocumentationMethodSample" />
</Routes>
}

}

Note: annotations are optional

ResponseBody And RequestBody

These annotations work as %RegisteredObject interpreters.
To use them, input the reference of your class as a value and the application will try to convert them to a representative JSON structure based on the object’s Properties.

Sample:

If you want to represent a JSON with the structure below:

{
    "Description": "String",
    "IsMultinational": true,
    "Name": "String",
    "QuantityEmployees": 544494327
}

Build a representative class as described below.

Class restApi.Model.Company Extends %RegisteredObject
{
Property Name As %String;
Property Description As %String;
Property QuantityEmployees As %Integer;
Property IsMultinational As %Boolean;
}

When you create a @ResponseBody or @RequestBody in your annotation, input the class reference like a @RequestBody(rest Api.Model.Company) and this JSON representation will appear in the documentation’s Body: section.

For more complex structures with lists of references to other objects or objects in properties, create the %RegisteredObject object Models and define its properties with them.

For example:

{
    "Address": "String",
    "Age": 880052597,
    "Children": [
        {
            "Age": 784503894,
            "Name": "String",
            "school": "String"
        }
    ],
    "Company": {
        "Description": "String",
        "IsMultinational": false,
        "Name": "String"
    },
    "HasChildren": true,
    "Name": "String"
}

create %RegisteredObject for children and Company;

restApi.Model.Company:

Class restApi.Model.Company Extends %RegisteredObject
{
    Property Name As %String;
    Property Description As %String;
    Property IsMultinational As %Boolean;
}

restApi.Model.Children:

Class restApi.Model.Children Extends %RegisteredObject
{
    Property Name As %String;
    Property Age As %Integer;
    Property school As %String;
}

And reference them in the properties of your main class:

Class restApi.Model.Sample Extends %RegisteredObject
{
    Property Name As %String;
    Property Address As %Library.String;
    Property Age As %Integer;
    Property HasChildren As %Boolean;
    Property Children As list Of restApi.Model.Children;
    Property Company As restApi.Model.Company;
}

Define this class at @ResponseBody() and this is the result: