2. What’s Swagger?
Agnostic definition language used for REST APIs
Machine and human readable
Allows discover and understand a service capabilities without acceding
source code, formal documentation, …
Swagger provides a toolbox ecosystem:
User interface
Code libraries
Language editor
Used by API Management solutions as Apigee, IBM, WSO2 among others.
jcopete.com
3. REST API basic definition
Minimal mandatory elements needed to define a REST API, using Swagger,
are:
Swagger: defines swagger version´s to be used, as last one is 2.0 we will use this
from now on.
Info: API metadata information
Title: API’s title or name
Description: short API description
Version: API version
Paths: holds different resources and API operations
jcopete.com
5. Defining response format
Different data types to be produced or consumed can be specified by
using “definitions” object.
So let´s define an “Error” data type with following properties:
code: integer in int32 format
message: a char string
fields: a char string
Let´s then define a “Product” data type with following properties:
productId: a char string
description: a char string
name: a char string
capacity: a char string
Image: a char string
jcopete.com
7. Defining API resources
To define API resources specify a “path” object. Previously we defined a
minimum products “path”.
Extend existing minimum products “path” with following attributes:
Tags: not mandatory, but will help when searching.
Summary: a brief definition for this operation.
Description: a detailed description for this operation.
operationId: a
Extendemos el “path” mínimo con los siguientes atributos:
tags: no es obligatorio, pero nos facilitará las búsquedas en el API.
summary: un pequeño resumen de la función de esta operación.
description: una descripción detallada de la operación.
operationId: un nombre único, y amigable, de operación.
jcopete.com
8. Defining API responses
Use “responses” object to define given responses for each resource
responses: composed of several elements (description, schema, headers,
examples), for this sample we will just use two of them:
description: response description. (Mandatory).
schema: defines response structure. It can be a basic type, a primitive or another
object already defined in “definitions” section.
For our example response for “products” resource will be defined using the definition that is
already created under “definitions” section. We will use a common error definition for
different scenarios.
jcopete.com
10. API parameters definition
“Parameters” object defines request parameters; For the example will
assume that all parameters are transferred by using a query-string.
Each parameter is defined in the following way:
name: parameter’s name (mandatory)
in: parameter type [ query, header, path, formData o body ]. (mandatory). We will use
query for this example.
description: short parameter description.
required: determines wether the parameter is mandatory. [ true, false ]
We will use 2 additional elements:
type: parameter type (mandatory if type is not body).
tormat: data type format previously defined.
jcopete.com