Edit

Swagger SDK

The ColdBox SwaggerSDK is a dependency of the Relax module and is available to allow you to provided consumers of your API with information on paths, methods, expectations and available parameters.

Hypermedia design patterns, usually provided within the content of OPTIONS requests to your endpoint, allow you to provide autodiscovery and consumption assistance on-the-fly.

For convenience, built-in methods are available within Relax to simplify the loading and parsing of your existing API documentation.

An example, leveraging an OPTIONS request for an endpoint (and using the conventions of the Coldbox REST API skeleton), might look like:

Routing config:

//Pet Routes - collections and additions
addRoute(
    pattern = "api/pets",
    handler = "Pets",
    action  = {
        "GET"    : "index",
        "POST"   : "create",
        "PUT"    : "onInvalidHTTPMethod",
        "PATCH"  : "onInvalidHTTPMethod",
        "DELETE" : "delete",
        "OPTIONS": "options"
    }
);

//Pet Routes - entity methods
addRoute(
    pattern = "api/pets/:id",
    handler = "Pets",
    action  = {
        "GET"    : "get",
        "POST"   : "onInvalidHTTPMethod",
        "PUT"    : "update",
        "PATCH"  : "update",
        "DELETE" : "delete",
        "OPTIONS": "options"
    }
);

Now we add an options method to our "Pets" handler to serve the documentation

This will serve information on the requested path of the petstore API as a JSON response to an OPTIONS request (using the collection example):

Hypermedia design patterns in your API responses, allow for self-discovery and ease development for API consumption.

PreviouscbSwagger Companion Module

Last updated