Warewolf supports Swagger and APIs.json

As part of our continued support to open source and open standards we have recently implemented both the APIs.json (for discovery) and Swagger v2.0 (for API definition and metadata).

This brings with it many advantages for anyone using Warewolf that wishes to have their services discovered automatically or give a standard way for others to consume their services. Furthermore, you as a Warewolf user don’t have to do anything special, or install anything extra. Every service that is created is automatically available for discovery (of course based on the security setup on the Server), as well as having the Swagger definition for the service available.

How to get to the APIs.json

 So how does one get to the APIs.json for a server? In keeping with being an “Easy Service Bus” we have made this super easy! All you have to do is run http://{SERVERNAME}:3142/apis.json, running this will produce something like the following (dependant on the services on your server and the security setup):

{
      "Name": "Dice Roll_test",
      "Description": null,
      "Image": null,
      "humanUrl": null,
      "baseUrl": "localhost:3142/secure/Examples/Dice Roll Example/Tests/Dice Roll_test.json",
      "Version": null,
      "Tags": null,
      "properties": [
        {
          "type": "Swagger",
          "value": "localhost:3142/secure/Examples/Dice Roll Example/Tests/Dice Roll_test.api"
        }
      ],
      "contact": null
    },
    {
      "Name": "Double Roll and Check_test",
      "Description": null,
      "Image": null,
      "humanUrl": null,
      "baseUrl": "localhost:3142/secure/Examples/Dice Roll Example/Tests/Double Roll and Check_test.json",
      "Version": null,
      "Tags": null,
      "properties": [
        {
          "type": "Swagger",
          "value": "localhost:3142/secure/Examples/Dice Roll Example/Tests/Double Roll and Check_test.api"
        }
      ],
      "contact": null
    },
    {
      "Name": "Hello World",
      "Description": null,
      "Image": null,
      "humanUrl": null,
      "baseUrl": "localhost:3142/secure/Hello World.json",
      "Version": null,
      "Tags": null,
      "properties": [
        {
          "type": "Swagger",
          "value": "localhost:3142/secure/Hello World.api"
        }
      ],
      "contact": null
    },
    {
      "Name": "Hello World",
      "Description": null,
      "Image": null,
      "humanUrl": null,
      "baseUrl": "localhost:3142/public/Hello World.json",
      "Version": null,
      "Tags": null,
      "properties": [
        {
          "type": "Swagger",
          "value": "localhost:3142/public/Hello World.api"
        }
      ],
      "contact": null
    }

Above is a snippet of some of the services available on my server. Now I have made reference to the fact that we show the services based on security setup of the server, this can be seen by the fact that there are two entries for my Hello Wold service in the definition above. One of the entries has “secure” in the base URL and the Swagger entry, the other has “public”. What this denotes is that my Hello World service is available as a secure service and it can be accessed anonymously as a publically available service.

Enter Swagger

As you can see in the snippet above in the properties section there is a property for “Swagger” and it has a value that follows the format {SERVERNAME}:{PORT}/{DIRECTORY}/{SERVICE}.api. In the case that my Hello World service is not in a directory to get to the Swagger definition I would go to http://localhost:3142/public/Hello World.api . For my service this will display:

{
  "swagger": 2,
  "info": {
    "title": "Hello World",
    "description": "",
    "version": "1.0.0"
  },
  "host": "localhost:3142/",
  "basePath": "/",
  "schemes": [
    "http",
    "https"
  ],
  "produces": "application/json",
  "paths": {
    "serviceName": "Hello World",
    "get": {
      "summary": "",
      "description": "",
      "parameters": [
        {
          "name": "Name",
          "in": "query",
          "required": true,
          "type": "string"
        }
      ]
    }
  },
  "responses": {
    "200": {
      "schema": {
        "$ref": "#/definition/Output"
      }
    }
  },
  "definitions": {
    "Output": {
      "type": "object",
      "properties": {
        "Message": {
          "type": "string"
        }
      }
    }
  }
}

This shows the Swagger definition for my Hello World service; similarly you can point to any of your services with the .api extension and see what the Swagger definition would be.

This obviously means that any system that is able to consume Swagger can now understand and automatically consume Warewolf services, no extra work for you, pretty cool huh?

Going forward there will be a way in the Studio to enter in some of the other meta data that is allowed by the definition, such as summary values and description values.

Well that’s it for this post. I hope this allows for even more awesome integration and makes using Warewolf even easier for you.