Permalink
38bc48c May 20, 2015
93 lines (81 sloc) 3.58 KB

Swagger Extensions

The Swagger 2.0 specification allows for custom properties to be added at several places within a Swagger definition, allowing API providers to extend the meta-data provided for their REST APIs as needed. Extension properties are always prefixed by "x-" and can have any valid JSON format value.

Currently extension properties are supported in the following definition objects:

For example, a vendor extension that adds apis.json specific metadata a Swagger definition might look as follows:

{
  "swagger": "2.0",
  "info": {
    "version": "1.0",
    "title": "Analysis",
    "description" : "Provides access to blog posts and analysis across the API Evangelist network.",
    "x-apis-json" : {
        "image": "https://s3.amazonaws.com/kinlane-productions/api-evangelist/t-shirts/KL_InApiWeTrust-1000.png",
        "humanURL": "http://developer.apievangelist.com",
        "baseURL": "http://api.apievangelist.com/definitions/Analysis",
        "tags": [
            "blog",
            "industry",
            "analysis",
            "new",
            "API",
            "Application Programming Interface"
        ],
        "properties": [
            {
                "type": "X-signup",
                "url": "https://apievangelist.3scale.net/"
            },
            {
                "type": "X-blog",
                "url": "http://developer.apievangelist.com/blog/"
            },
            {
                "type": "X-apicommonsmanifest",
                "url": "https://raw.githubusercontent.com/kinlane/analysis-api/master/api-commons-manifest.json"
            }
        ],
     }
  },
  "basePath": "/",
  "paths": {
     ...
  }
}

This could be used by corresponding tooling that builds apis.json files for swagger definitions, the advantage being that all metadata for a Swagger API is within one definition instead of spread out amongst multiple files.

Another (simplified) example could be how to specify a JWE encryption policy to parameters, for example as follows:

{
  ...
    "socialSecurityNumber": {
      "name": "socialSecurityNumber",
      "in": "query",
      "description": "a social security number",
      "required": false,
      "type": "string",
      "x-jwe-encryption" : {
          "algorithm" : "RSA-OAEP",
          "encryption" : "A256GCM"
       }
    }
  }
  ...
}

An API consumer reading these parameter definitions could interpret this as having to encrypt the skip parameter in line with the JWE standard.

Annotations

The Swagger specific annotations currently available for jax-rs APIs do not support the addition of extension data.