## Introduction to Swagger
#### 15.03.16 / Web API Meetup / Wer liefert Was?
[@NilsLoewe](https://twitter.com/NilsLoewe)
## What is Swagger?
### Swagger is a representation for REST APIs: * Interactive documentation * Client SDK generation * Discoverability * Supporting many programming languages and environments * 100% Open Source
### What's Open Source in this case?
#### 2011-08-10: First release of the Swagger Specification To bring the “good parts” of REST, SOAP, Web Services and RPC into a simple, easy to understand format.
#### 2014-09-08: Release of Swagger 2.0 Swagger tools are downloaded close to 15,000 times per day.
2000 known open-source repositories for Swagger tools
First-class support across all major API management platforms.
#### 2016-01-01 The Open API Initiative ### Part of the Linux Foundation
*Founding partners: Google, Microsoft, IBM, 3Scale, Apigee, CapitalOne, Intuit, PayPal, and Restlet.*
[openapis.org](https://openapis.org)
![](/images/oai.png)
## How to use Swagger?
#### New API: Top-Down * Use the Swagger **Editor** to create your Swagger definition * Use the Swagger **Codegen** tools to generate server implementation
#### Existing API: Bottom-Up * You have an existing REST API * You want to create a Swagger definition * Option A: Create the definition manually using the Swagger Editor * Option B: Integrate the framework into your Code and get the Swagger definition generated automatically
#### Build a new client for a Swagger-described API * Use the online version of the Swagger UI to explore the API * (given that you have a URL to the APIs Swagger definition) * Use Swagger Codegen to generate the client library
## Swagger Tools
#### Swagger-Codegen *Generating client libraries and server stubs from a Swagger definition* * Required: Java 7, Apache maven > 3.0.3 * Available via homebrew, Docker, Vagrant, ... * https://github.com/swagger-api/swagger-codegen
#### Swagger-UI *A dependency-free collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation and sandbox from a Swagger-compliant API* * Works in all common browsers (Chrome, Safari, Firefox, IE8++) * Download from https://github.com/swagger-api/swagger-ui
#### Available Integrations *Open Source Implementations available for*
Clojure, Coldfusion, D, Eiffel, Erlang, Go, Groovy, Haskell, Java, Javascript, TypeScript, .NET, Node.JS, Perl, Python, Php, Ruby, Scala
*Commercial Implementations available for*
http://swagger.io/commercial-tools/
### Describing APIs with Swagger

A 'hello world' API

swagger: "2.0"
info:
  version: "1.0"
  title: "Hello World API"
paths:
  /hello/{user}:
    get:
      description: Returns a greeting to the user!
      parameters:
        - name: user
          in: path
          type: string
          required: true
          description: The name of the user to greet.
      responses:
        200:
          description: Returns the greeting.
          schema:
            type: string
        400:
          description: Invalid characters in "user" were provided.

API Info

title           string	Required. The title of the application.
description     string	A short description of the application.
termsOfService	string	The Terms of Service for the API.
contact	        Object	The contact information for the exposed API.
license	        Object	The license information for the exposed API.
version	        string	Required Provides the version of the application API

Data types

integer   integer   int32       signed 32 bits
long      integer   int64       signed 64 bits
float	  number    float
double	  number    double
string	  string
byte	  string    byte	        base64 encoded characters
binary	  string    binary      any sequence of octets
boolean	  boolean
date	  string    date	        As defined by full-date - RFC3339
dateTime  string    date-time	As defined by date-time - RFC3339
password  string    password	Used to hint UIs the input needs to be obscured.

Schemes

swagger	  string	Required. Specifies the Swagger Specification version
info	  Info Object	Required. Provides metadata about the API
host	  string	The host (name or ip) serving the API
basePath  string	The base path on which the API is served, relative to the host
schemes   [string]	The transfer protocol: "http", "https", "ws", "wss"
consumes  [string]	A list of MIME types the APIs can consume
produces  [string]	A list of MIME types the APIs can produce
paths	  Paths Object	Required. The available paths and operations for the API.
...
http://swagger.io/specification/
### Demo Time! http://petstore.swagger.io/
### Thank you!
https://slides.nils-loewe.de/
[@NilsLoewe](https://twitter.com/NilsLoewe)