Documentation Configuration

Name	Purpose
`language`	The tag identifying the primary language of the documentation. Some sections will render metadata in this language if it is available. If not set, the `sapi-nt.config.preferredLanguage` will be used by default.
`vocabularySource`	The name of the data source that should be used for extracting vocabulary statements
`externalVocabulary`	A comma separated list of external turtle files holding the vocabulary data
`introduction`	Specifies an introduction section of the documentation. Can be specified as a string where every new line denotes a new paragraph or as a pointer to an external HTML file
`example`	Specifies query, result and filter examples used in the API Structure section of the documentation. These should all be derived from the same example query.
`groups`	A list of high-level groupings to be summarised in the API Summary section
`classes`	A list of classes to be rendered as sections of the documentation. These may be the same as the groupings specified by `groups`, or more granular

Configuration Example

language: en
introduction:
  filePath: classpath:external-introduction.html
example:
  query: /protected-area/id?_limit=10
  jsonItem: >
    {
      "@id": "http://environment.data.gov.uk/protected-area/id/sac/UK0030372",
      "protectedAreaType": {
        "@id": "http://environment.data.gov.uk/catchment-planning/def/protected-area/habitats-and-species-directive",
        "label": "Habitats and Species Directive"
      },
      ...
    }
  filter:
    description: "For example, to list just protected areas of type Special Area of Conservation (SAC) use:"
    query: /protected-area/id?type=SAC
groups:
- id: protected-area
  label: Protected Areas
  description:
    content: "You can access information about protected areas by sending a request to these endpoints."
  endpoints: [protected-area, protected-areas]
  displayProperties: [Name, API]
classes:
- id: protected-area
  label: Protected Areas
  description:
    content: "You can access information about <b>protected areas</b> by sending a request to these endpoints."
  endpoints: [protected-area, protected-areas]
  examples:
  - description: "List just SAC protected areas, show first 50 results:"
    query: /protected-area/id?type=SAC&_limit=50

Introduction

Name	Purpose
`filePath`	A path to a file on the class path containing the introduction content in HTML or Markdown format.
`content`	The raw introduction content in HTML or Markdown format. If this is set, `filePath` will be ignored. If the format is HTML, a new line denotes a new paragraph.
`format`	The format of the introduction content, either `html` or `markdown`. Defaults to `html`.

Introduction Example

filePath: classpath:external-introduction.md
format: markdown

content: |
  The Water Quality Archive provides data on water quality measurements carried out by the Environment Agency. 
  Samples are taken from sampling points round the country and then analysed by laboratories to measure aspects of the water quality or the environment at the sampling point. 
  The archive provides data on these measurements and samples dating from 2000 to present day. It contains 58 million measurements on nearly 4 million samples from 58 thousand sampling points.

Example

Name	Purpose
`query`	An example relative query URI used in the API Structure section
`jsonItem`	A json result example used to demonstrate result format in the API Structure section
`filter`	An example filter containing a description and a URI demonstrated in the API Structure section

Example Example

query: /protected-area/id?_limit=10
jsonItem: >
  {
    "@id": "http://environment.data.gov.uk/protected-area/id/sac/UK0030372",
    "protectedAreaType": {
      "@id": "http://environment.data.gov.uk/catchment-planning/def/protected-area/habitats-and-species-directive",
      "label": "Habitats and Species Directive"
    },
    ...
  }
filter:
  description: "For example, to list just protected areas of type Special Area of Conservation (SAC) use:"
  query: /protected-area/id?type=SAC

Filter

Name	Purpose
`description`	Description of the filter
`query`	An example filter relative URI

Example Filter

description: "For example, to list just assets of type Outfall, we can use:"
query: /id/asset?assetSubType=Outfall

Groups and Classes

Name	Purpose	Supported By
`id`	A unique identifier used for setting section anchors	All
`label`	A label used to set the section header	All
`description`	A description used to describe the group/class in detail. Has same format as introduction	All
`endpoints`	A list of endpoint names that belong to the group/class	All
`displayProperties`	A list of properties to be listed in the endpoint table. Optional - by default it includes all properties, i.e. Name, Description and Parameters	All
`examples`	A list of examples including the description and the relative URI that are listed at the end of each class section. Has same format as filter	Classes Only

Example Class

id: protected-area
label: Protected Areas
description:
  content: "You can access information about <b>protected areas</b> by sending a request to these endpoints."
endpoints: [protected-area, protected-areas]
examples:
- description: "List just SAC protected areas, show first 50 results:"
  query: /protected-area/id?type=SAC&_limit=50

Endpoint Configuration

Name	Purpose
`description`	A brief description of the endpoint’s functionality
`example`	An example of a URI which calls the endpoint. If possible, this should be the location of a real page served by the API. If this property is ommitted, the `url` property of the endpoint will be given as an example instead.
`documentationParameters`	A mapping of useful query parameters to their types. Standard query params will be added automatically

Endpoint Configuration Example

description: List Protected Areas
example: /protected-areas
documentationParameters:
      "protectedAreaType" : "id"
      "notation" : "value"