This document discusses how to define REST APIs using the Swagger definition language. It provides an overview of Swagger and its capabilities for documenting APIs. It then demonstrates how to define the basic elements of an API in Swagger, including metadata, data types, resources, responses, and parameters.

1. Defining APIs using
Swagger
JOAQUIN COPETE
JCOPETEG@GMAIL.COM

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

4. REST API basic definition
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

6. Defining response format
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

9. Responses
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

11. Parameters
jcopete.com

12. Thanks
Joaquin copete
jcopeteg@gmail.com
jcopete.com