Bring some Swagger to your APIs
Posted by Dion Almaer about a year ago on opensource services
Whether you offer third party access to your APIs, or you offer them up for internal use, you should take a look at adding some Swagger to your step.
The new open source framework comes from Wordnik and the awesome Tony Tam. They have long offered up APIs to their vast data and services with a variety of client side SDKs that work with their REST APIs.
Now we know how they have done so. Swagger draws a thread between any client talking through to RESTful services:
The overarching goal of Swagger is to enable client and documentation systems to update at the same pace as the server. The documentation of methods, parameters and models are tightly integrated into the server code, allowing APIs to always stay in sync. With Swagger, deploying managing, and using powerful APIs has never been easier.
The Swagger framework simultaneously solves server, client, and documentation/sandbox needs. As a specification, it is language-agnostic. It also provides a long runway into new technologies and protocols beyond REST.
With Swagger’s declarative resource specification, clients can understand and consume services without knowledge of server implementation or access to the server code. The Swagger UI framework allows both developers and non-developers to interact with the API in a sandbox UI that gives clear insight into how the API responds to parameters and options.
Swagger happily speaks both JSON and XML, with additional formats in the works.
Core to Swagger is the specification of RESTful web services. This includes three major components: resource discovery, resource declaration and input/output model declaration.
At the heart you end up (can be autogenerated from the Java/Scala system say) with JSON defining your API plaground:
// Sample resource listing
{
"apis":[
{
"path":"/photo",
"description":""
}
],
"basePath":"url",
"swagrVersion":"0.1a",
"apiVersion":"1.0.1a"
}
// Sample operation listing
{
"apis":[
{
"path":"/photo/{userId}",
"description":"",
"operations":[
{
"parameters":[
{
"name":"userId",
"description":"ID of User whose photos",
"dataType":"string",
"allowMultiple":false,
"required":true,
"allowableValues":[
"allowedId1",
"allowedId2",
"allowedId3"
],
"paramType":"path"
}
],
"httpMethod":"GET",
"tags":[
"DM",
"PD"
],
"nickname":"getPhotosById",
"responseClass":"List[photo]",
"deprecated":false,
"open":false,
"summary":"Fetches photos by UserId"
}
],
"errorResponses":[
{
"reason":"Invalid ID supplied",
"code":400
},
{
"reason":"Not Authorized to access User",
"code":403
},
{
"reason":"User not found",
"code":404
}
]
}
],
"models":{
"photo":{
"properties":{
"title":{
"type":"string"
},
"url":{
"type":"string",
"description":"Url for photo",
"access":"restricted",
"notes":"Sample note for a url",
"enum":[
"a",
"b",
"c"
]
}
},
"id":"photo"
}
},
"basePath":"url",
"swagrVersion":"0.1a",
"apiVersion":"1.0.1a"
}
From there you have the API explorer that gives developers a great way to discover and explore.
It seems very polished for an initial launch, and I am excited to see how it grows from here. Checkout the pieces on GitHub.