Add a 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

To define documentation and make it linked with the service you need to create a new schema.

Now we need to define the required columns for the documentation. For this example, we are going to use a simple structure. We will have only one property URL. We can do it in the following section:

Full JSON for the "From JSON Schema"

{
  "type": "object",
  "properties": {
    "URL": {
      "description": "Provide a URL for a JSON/YAML file that will be rendered into documentation",
      "type": "string"
    }   
  }
}

Our next step is to add an additional column for this schema or use the auto-generator.

The only thing left is to add the relation between the Service and Documentation.

Finally, click Save and Create your schema.

2. Create a custom plugin template

Next, go back to the recently created Documentation schema and create a custom plugin template.

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

By URL field an entity should have a public link to JSON or YAML file with OpenAPI Specification (v2 and v3 are supported)

Click Save and Update your schema.

After the schema creation, you will see that a new item appears in the catalog menu:

3. Add Documentation entity

Now you can add new documentation. Click on the documentation item and you will be navigated to the documentation list page.

Press the Add New Entity button. You must fill in the data with the following, select your service(s) and press the add button.

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

You can see two tabs on this entity page. The first one contains entity details and the second one lists the services that are attached to this documentation. Switch to the services tab and select My Service, you will be navigated to the service overview page.

4. Add Swagger UI plug-in

Click Add Plug-in button and select created by you Swagger UI plug-in.

As a result, you can see your documentation in Swagger UI.

If your service has more than one documentation create Swagget UI plug-on for every instance and use custom plugin filters, or see them in the list.

[
    {
        "filters": [
            {
                "compare": "eq",
                "field": "name",
                "type": "compare",
                "value": "My Documentation"
            }
        ]
    }
]