Skip to content

Implementing the Swagger API Specification

Jump to bottom
Bridget Almas edited this page Mar 22, 2017 · 3 revisions

Compliance

To be compliant with the DTS Swagger API Specification, your implementation must:

  1. Serve the swagger.json specification
  2. Answer at the paths identified by combining the host,schemes,basePath with individual paths defined in the paths property of the specification. a. This includes the parameters listed for each request.
  3. Return responses which adhere in both structure and HTTP response code value to those defined in the specification for each path. In addition the, HTTP content-type headers returned by your server at those addresses must adhere to the values listed in the produces property of the spec.

Instructions for serving the swagger.json specification

  1. Publish a route which returns the specification JSON document.

    e.g. http://example.org/api/apidocs

    It can be a good idea to allow room for a version identifier in that route, in case a new version of the specification is published.

    e.g. http://example.org/api/v1.0.0/apidocs

  2. Before serving it, you must change the values in the specification JSON document which are specific to the deployment:

 "host": "<your hostname>",

host should be set to the hostname of your service. It should not include the scheme (i.e. http or https)


"schemes": [<https|http>],

schemes should be set to a list of the schemes you serve the API at, in order of preference. If you don't have an SSL certificate for your server, then the value for schemes should just be ["http"]. If you do have an SSL certificate, then it's preferred to list that first: ["https","http"].

"basePath": "<path prefix for api requests>",

basePath should be set to the root path prefix, if any, that you serve the API requests at.

Client applications will expect to form requests to your API endpoint by combining the schemes, host and basePath values, and then access the paths advertised in the rest of the specification at that location.

So, for example, with the the following values...

"host": "example.org",
"schemes": ["https"],
"basePath": "api/v1.0.0",

...clients to your API should be able to expect to make calls to the following addresses:

https://example.org/api/v1.0.0/collections

https://example.org/api/v1.0.0/collections/{id}

https://example.org/api/v1.0.0/collections/{id}/capabilities

https://example.org/api/v1.0.0/collections/{id}/metadata

Everything from /collections on in the path of the request should be standard across ALL implementations of the API. These paths are defined in the paths property of the specification JSON document.

The combination of the host,schemes and basePath values are specific to individual implementations.

If your service requires authentication, this information can also be expressed via the specification. For more information on the above points and instructions on implementation authentication protocols, see the Swagger Specification

Testing

Once you have completed the above steps, you should be able to test your API using the Swagger-UI that is deployed in the Distributed Text Services GitHub Pages at https://distributed-text-services.github.io/collection-api/

  1. Enter the url at which you serve the swagger specification in the input box at the top of the UI and click Explore.

  2. You should see the Collections topic and be able to click Expand Operations to see the list of all the available operations.

  3. Use the Try it Out! Buttons for each operation to test the request/response to your API.

Clone this wiki locally