Embed Size (px)
Citation preview
Defining APIs using SwaggerJOAQUIN [email protected]
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
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
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
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
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
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
