The REST API Swagger documentation

Many of the execute and management REST API methods in a Corticon Server WAR file can be exposed in Swagger, the popular OpenAPI Specification tool for describing, producing, consuming, and visualizing RESTful Web services. Swagger is built-in to every Corticon Server installation; however, it is not, by default, enabled.

You can use Swagger through BASIC authentication and HTTPS connections.

Enabling Swagger on Tomcat

To enable Swagger on a Tomcat server installation:

1. Confirm that the installation has <Corticon_Home>/Server/Swagger/CcSwagger.jar.

2. Copy CcSwagger.jar, and then paste it into <Tomcat>/webapps/axis/WEB-INF/lib. That effectively adds the JAR to the server classpath.

3. Edit <Tomcat>/webapps/axis/WEB-INF/web.xml to change the parameter value for enabling Swagger to true:

   Copy

   <init-param>
     <param-name>corticon.swagger.enabled</param-name>
     <param-value>true</param-value>
   </init-param>
   

4. Save your edited file, and then restart the server.

5. In your browser enter http://localhost:8850/axis/swagger/

The Corticon Server REST APIs page opens, as shown:

Accessing Swagger on a Corticon Server for Java

To access Swagger and the exposed REST methods, enter the following URL into a browser on a machine where Corticon Server is installed and running:

http://localhost:port/context/swagger

where the URL for typical local installation using HTTP is:

http://localhost:8850/axis/swagger

Adjusting Swagger access for custom ports and contexts

If you want to specify a preferred port or a context other than axis, you need to adjust some Swagger configurations.

To use a different port, for example for secure HTTP on port 8851:

1. Edit the file:

   Copy

   [CORTICON_HOME]\Server\tomcat\webapps\axis\swagger\index.html
   

   to change the url line to:

   Copy

   url = "https://localhost:8851/axis/corticon/swagger.json";
   

   Note: On 6.1 and earlier:

   Copy

   url = "http://localhost:8851/axis/corticon/openapi.json"
   

   and then save the file.

To use a different context, for example Java_UAT:

1. Stop the server.

2. Edit the file:

   Copy

   [CORTICON_HOME]\Server\tomcat\webapps\axis\swagger\index.html
   

   to change the url line to:

   Copy

   url = "https://localhost:8851/Java_UAT/corticon/swagger.json";
   

   Note: On 6.1 and earlier:

   Copy

   url = "http://localhost:8851/Java_UAT/corticon/openapi.json"
   

3. Save the file.

4. Edit the file:

   Copy

   [CORTICON_HOME]\Server\tomcat\webapps\axis\web.xml
   

   to change the swagger.api.basepath parameter value to:

   Copy

   <param-value>/Java_UAT/corticon</param-value>
   

5. Save your edited file, and then restart the server.

Disabling Swagger on a Server

To disable Swagger on a Server:

1. Edit <Tomcat>/webapps/axis/WEB-INF/web.xml to change the parameter value for enabling Swagger to false:

   Copy

   <init-param>
     <param-name>corticon.swagger.enabled</param-name>
     <param-value>false</param-value>
   </init-param>
   

2. Save your edited file, and then restart the server.

When you restart the server, access to Swagger on the Server is disabled.