$30 off During Our Annual Pro Sale. View Details »

Introduction to Swagger

Introduction to Swagger

Talk at the WebAPI Meetup in Hamburg 2016

Nils Löwe

March 15, 2016
Tweet

More Decks by Nils Löwe

Other Decks in Programming

Transcript

  1. Introduction to Swagger
    15.03.16 / Web API Meetup / Wer liefert Was?
    @NilsLoewe

    View Slide

  2. What is Swagger?

    View Slide

  3. Swagger is a representation for REST APIs:
    Interactive documentation
    Client SDK generation
    Discoverability
    Supporting many programming languages and
    environments
    100% Open Source

    View Slide

  4. What's Open Source in this case?

    View Slide

  5. 2011-08-10: First release of the Swagger Speci cation
    To bring the “good parts” of REST, SOAP, Web Services and
    RPC into a simple, easy to understand format.

    View Slide

  6. 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.

    View Slide

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

    View Slide

  8. View Slide

  9. How to use Swagger?

    View Slide

  10. New API: Top-Down
    Use the Swagger Editor to create your Swagger de nition
    Use the Swagger Codegen tools to generate server
    implementation

    View Slide

  11. Existing API: Bottom-Up
    You have an existing REST API
    You want to create a Swagger de nition
    Option A: Create the de nition manually using the
    Swagger Editor
    Option B: Integrate the framework into your Code and get
    the Swagger de nition generated automatically

    View Slide

  12. 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 de nition)
    Use Swagger Codegen to generate the client library

    View Slide

  13. Swagger Tools

    View Slide

  14. Swagger-Codegen
    Generating client libraries and server stubs from a Swagger
    de nition
    Required: Java 7, Apache maven > 3.0.3
    Available via homebrew, Docker, Vagrant, ...
    https://github.com/swagger-api/swagger-codegen

    View Slide

  15. 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

    View Slide

  16. 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/

    View Slide

  17. Describing APIs with Swagger

    View Slide

  18. A 'hello world' API
    s
    w
    a
    g
    g
    e
    r
    : "
    2
    .
    0
    "
    i
    n
    f
    o
    :
    v
    e
    r
    s
    i
    o
    n
    : "
    1
    .
    0
    "
    t
    i
    t
    l
    e
    : "
    H
    e
    l
    l
    o W
    o
    r
    l
    d A
    P
    I
    "
    p
    a
    t
    h
    s
    :
    /
    h
    e
    l
    l
    o
    /
    {
    u
    s
    e
    r
    }
    :
    g
    e
    t
    :
    d
    e
    s
    c
    r
    i
    p
    t
    i
    o
    n
    : R
    e
    t
    u
    r
    n
    s a g
    r
    e
    e
    t
    i
    n
    g t
    o t
    h
    e u
    s
    e
    r
    !
    p
    a
    r
    a
    m
    e
    t
    e
    r
    s
    :
    ­ n
    a
    m
    e
    : u
    s
    e
    r
    i
    n
    : p
    a
    t
    h
    t
    y
    p
    e
    : s
    t
    r
    i
    n
    g
    r
    e
    q
    u
    i
    r
    e
    d
    : t
    r
    u
    e
    d
    e
    s
    c
    r
    i
    p
    t
    i
    o
    n
    : T
    h
    e n
    a
    m
    e o
    f t
    h
    e u
    s
    e
    r t
    o g
    r
    e
    e
    t
    .
    r
    e
    s
    p
    o
    n
    s
    e
    s
    :
    2
    0
    0
    :
    d
    e
    s
    c
    r
    i
    p
    t
    i
    o
    n
    : R
    e
    t
    u
    r
    n
    s t
    h
    e g
    r
    e
    e
    t
    i
    n
    g
    .
    s
    c
    h
    e
    m
    a
    :

    View Slide

  19. API Info
    t
    i
    t
    l
    e s
    t
    r
    i
    n
    g R
    e
    q
    u
    i
    r
    e
    d
    . T
    h
    e t
    i
    t
    l
    e o
    f t
    h
    e a
    p
    p
    l
    i
    c
    a
    t
    i
    o
    n
    .
    d
    e
    s
    c
    r
    i
    p
    t
    i
    o
    n s
    t
    r
    i
    n
    g A s
    h
    o
    r
    t d
    e
    s
    c
    r
    i
    p
    t
    i
    o
    n o
    f t
    h
    e a
    p
    p
    l
    i
    c
    a
    t
    i
    o
    n
    .
    t
    e
    r
    m
    s
    O
    f
    S
    e
    r
    v
    i
    c
    e s
    t
    r
    i
    n
    g T
    h
    e T
    e
    r
    m
    s o
    f S
    e
    r
    v
    i
    c
    e f
    o
    r t
    h
    e A
    P
    I
    .
    c
    o
    n
    t
    a
    c
    t O
    b
    j
    e
    c
    t T
    h
    e c
    o
    n
    t
    a
    c
    t i
    n
    f
    o
    r
    m
    a
    t
    i
    o
    n f
    o
    r t
    h
    e e
    x
    p
    o
    s
    e
    d A
    P
    I
    .
    l
    i
    c
    e
    n
    s
    e O
    b
    j
    e
    c
    t T
    h
    e l
    i
    c
    e
    n
    s
    e i
    n
    f
    o
    r
    m
    a
    t
    i
    o
    n f
    o
    r t
    h
    e e
    x
    p
    o
    s
    e
    d A
    P
    I
    .
    v
    e
    r
    s
    i
    o
    n s
    t
    r
    i
    n
    g R
    e
    q
    u
    i
    r
    e
    d P
    r
    o
    v
    i
    d
    e
    s t
    h
    e v
    e
    r
    s
    i
    o
    n o
    f t
    h
    e a
    p
    p
    l
    i
    c
    a
    t
    i
    o
    n A
    P
    I

    View Slide

  20. Data types
    i
    n
    t
    e
    g
    e
    r i
    n
    t
    e
    g
    e
    r i
    n
    t
    3
    2 s
    i
    g
    n
    e
    d 3
    2 b
    i
    t
    s
    l
    o
    n
    g i
    n
    t
    e
    g
    e
    r i
    n
    t
    6
    4 s
    i
    g
    n
    e
    d 6
    4 b
    i
    t
    s
    f
    l
    o
    a
    t n
    u
    m
    b
    e
    r f
    l
    o
    a
    t
    d
    o
    u
    b
    l
    e n
    u
    m
    b
    e
    r d
    o
    u
    b
    l
    e
    s
    t
    r
    i
    n
    g s
    t
    r
    i
    n
    g
    b
    y
    t
    e s
    t
    r
    i
    n
    g b
    y
    t
    e b
    a
    s
    e
    6
    4 e
    n
    c
    o
    d
    e
    d c
    h
    a
    r
    a
    c
    t
    e
    r
    s
    b
    i
    n
    a
    r
    y s
    t
    r
    i
    n
    g b
    i
    n
    a
    r
    y a
    n
    y s
    e
    q
    u
    e
    n
    c
    e o
    f o
    c
    t
    e
    t
    s
    b
    o
    o
    l
    e
    a
    n b
    o
    o
    l
    e
    a
    n
    d
    a
    t
    e s
    t
    r
    i
    n
    g d
    a
    t
    e A
    s d
    e
    f
    i
    n
    e
    d b
    y f
    u
    l
    l
    ­
    d
    a
    t
    e ­ R
    F
    C
    3
    3
    3
    9
    d
    a
    t
    e
    T
    i
    m
    e s
    t
    r
    i
    n
    g d
    a
    t
    e
    ­
    t
    i
    m
    e A
    s d
    e
    f
    i
    n
    e
    d b
    y d
    a
    t
    e
    ­
    t
    i
    m
    e ­ R
    F
    C
    3
    3
    3
    9
    p
    a
    s
    s
    w
    o
    r
    d s
    t
    r
    i
    n
    g p
    a
    s
    s
    w
    o
    r
    d U
    s
    e
    d t
    o h
    i
    n
    t U
    I
    s t
    h
    e i
    n
    p
    u
    t n
    e
    e
    d
    s t
    o b
    e o
    b
    s
    c
    u
    r
    e
    d
    .

    View Slide

  21. Schemes
    s
    w
    a
    g
    g
    e
    r s
    t
    r
    i
    n
    g
    R
    e
    q
    u
    i
    r
    e
    d
    . S
    p
    e
    c
    i
    f
    i
    e
    s t
    h
    e S
    w
    a
    g
    g
    e
    r S
    p
    e
    c
    i
    f
    i
    c
    a
    t
    i
    o
    n v
    e
    r
    s
    i
    o
    n
    i
    n
    f
    o I
    n
    f
    o O
    b
    j
    e
    c
    t R
    e
    q
    u
    i
    r
    e
    d
    . P
    r
    o
    v
    i
    d
    e
    s m
    e
    t
    a
    d
    a
    t
    a a
    b
    o
    u
    t t
    h
    e A
    P
    I
    h
    o
    s
    t s
    t
    r
    i
    n
    g
    T
    h
    e h
    o
    s
    t (
    n
    a
    m
    e o
    r i
    p
    ) s
    e
    r
    v
    i
    n
    g t
    h
    e A
    P
    I
    b
    a
    s
    e
    P
    a
    t
    h s
    t
    r
    i
    n
    g
    T
    h
    e b
    a
    s
    e p
    a
    t
    h o
    n w
    h
    i
    c
    h t
    h
    e A
    P
    I i
    s s
    e
    r
    v
    e
    d
    , r
    e
    l
    a
    t
    i
    v
    e t
    o t
    h
    e
    s
    c
    h
    e
    m
    e
    s [
    s
    t
    r
    i
    n
    g
    ] T
    h
    e t
    r
    a
    n
    s
    f
    e
    r p
    r
    o
    t
    o
    c
    o
    l
    : "
    h
    t
    t
    p
    "
    , "
    h
    t
    t
    p
    s
    "
    , "
    w
    s
    "
    , "
    w
    s
    s
    "
    c
    o
    n
    s
    u
    m
    e
    s [
    s
    t
    r
    i
    n
    g
    ] A l
    i
    s
    t o
    f M
    I
    M
    E t
    y
    p
    e
    s t
    h
    e A
    P
    I
    s c
    a
    n c
    o
    n
    s
    u
    m
    e
    p
    r
    o
    d
    u
    c
    e
    s [
    s
    t
    r
    i
    n
    g
    ] A l
    i
    s
    t o
    f M
    I
    M
    E t
    y
    p
    e
    s t
    h
    e A
    P
    I
    s c
    a
    n p
    r
    o
    d
    u
    c
    e
    p
    a
    t
    h
    s P
    a
    t
    h
    s O
    b
    j
    e
    c
    t R
    e
    q
    u
    i
    r
    e
    d
    . T
    h
    e a
    v
    a
    i
    l
    a
    b
    l
    e p
    a
    t
    h
    s a
    n
    d o
    p
    e
    r
    a
    t
    i
    o
    n
    s f
    o
    r
    .
    .
    .
    h
    t
    t
    p
    :
    /
    /
    s
    w
    a
    g
    g
    e
    r
    .
    i
    o
    /
    s
    p
    e
    c
    i
    f
    i
    c
    a
    t
    i
    o
    n
    /

    View Slide

  22. Demo Time!
    http://petstore.swagger.io/

    View Slide

  23. Thank you!
    https://slides.nils-loewe.de/
    @NilsLoewe

    View Slide