Add a API Documentation Schema and Swagger UI plugin

This sample step-by-step configuration is to expand your services data in configure8 with documentation. It can be adapted to extend your services with other types of data.

1. Create a schema

Creating a new schema to define documentation and link it with the service would be best.

Form JSON Schema

Full JSON for the "From JSON Schema"

{
  "type": "object",
  "required": [
    "URL"
  ],
  "properties": {
    "URL": {
      "description": "",
      "type": "string"
    },
    "version": {
      "description": "",
      "type": "string"
    }
  }
}

Data Model JSON

We will configure how to display this information in the API Docs table.

[
  {
    "hidden": false,
    "name": "URL",
    "columnName": "IFrame URL",
    "calc": "details.URL",
    "format": {
      "link": "{self}",
      "displayValue": {
        "type": "string",
        "value": "{self}"
      }
    }
  },
  {
    "hidden": false,
    "name": "version",
    "columnName": "Version",
    "calc": "details.version",
    "format": {
      "displayValue": {
        "type": "string",
        "value": "v{self}"
      },
      "label": {
        "type": "tag",
        "options": [
          {
            "color": "rgba(224, 224, 224, 1)"
          }
        ]
      }
    }
  }
]

Relations

We need to add the relation between the Service and API Docs.

In this sample, we are using Many to Many as one document can belong to multiple services, but maybe that's not the case in your organization.

Finally, click Save and Create your schema.

Tabs

Enter the newly created schema again to add a new tab displaying the embedded SwaggerUI with the API Documentation.

Create a new Tab called "API Doc", and under that tab, a new widget called API Doc with the following content:

[
  {
    "displayType": "swaggerUI",
    "item": {
      "title": "{{ item.name }} v{{item.details.version}}",
      "subtitle": "{{item.details.description}}",
      "url": "{{ item.details.URL }}"
    }
  }
]

If you want to see the API Docs embedded in a tab on your services page, extend your service schema and add a tab with a widget like the above.

2. Add API Docs entities

Now, you can add new API Docs to your catalog. Click on the documentation item to go to the API Docs list page.

Press the Add New Entity button. You must fill in the data by selecting your service(s) and pressing the add button.

After successfully creating the entity you will need to navigate to its page:

You can see three tabs on this entity page. The first one contains entity details, the second one lists the services that are attached to this documentation, and the third one shows the embedded view of that API Docs:

Seeing the API Docs inside a the service page after adding the tab and widget to services schema: