Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Build Swagger definition - Sample

Create your REST API Swagger definition from scratch with this simple example.

  • Be the first to comment

Build Swagger definition - Sample

  1. 1. Defining APIs using Swagger JOAQUIN COPETE JCOPETEG@GMAIL.COM
  2. 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. 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. 4. REST API basic definition jcopete.com
  5. 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. 6. Defining response format jcopete.com
  7. 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. 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. 9. Responses jcopete.com
  10. 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. 11. Parameters jcopete.com
  12. 12. Thanks Joaquin copete jcopeteg@gmail.com jcopete.com

    Be the first to comment

    Login to see the comments

  • systemsmgmtzen

    Apr. 22, 2016

Create your REST API Swagger definition from scratch with this simple example.

Views

Total views

357

On Slideshare

0

From embeds

0

Number of embeds

8

Actions

Downloads

5

Shares

0

Comments

0

Likes

1

×