# Swagger

### GolangSF, January 20, 2016

Ivan Porto Carrero

VMware

### About me

Did a bunch of work on/with swagger:

- Wrote scalatra
- Worked at Reverb
- Contributed async scala client to codegen
- Wrote go-swagger

## So you think you wanna microservice huh

### Read the source!

### Stale documentation

### Lots of communication required

### Bottlenecks

### Customers don't want to write your SDK

### All too often...

- conflicts
- blame game
- Cover Your Ass

### Some requirements

Humans want up to date documentation to read

Consumers need an exhaustive contract
Different teams, different programming languages

Introspection would be a plus
DRY at application level would be nice

### More sadness

- many deploys, all the time
- distributed system complexity
- tooling relatively primitive

### Enter swagger

Open standard on Linux Foundation

An interface to your service, described in JSON

A language/platform/deployment agnostic contract to your service

Enables "bigotry-free" restful design with emphasis on Getting Things Done.

Machine readable exhaustive contract of server abilities

Server controlled documentation

## You had me at tooling

### Orthogonal toolkit

- spec validator with extra semantic validations
- client generation
- server generation
- spec generation for any application
- documentation lives with the code
- go:generate integration

### Client SDKs

- statically typed
- regenerated imported on contract change
- frontend and mobile client teams
- other service clients
- 30+ languages through swagger-codegen

### Go Swagger server

- Spec remains source of thruth
- can be used as focal point of discussion/meetings
- swagger meta data
- routing
- security
- request validation
- reuse `net/http` style middleware: `func(http.Handler) http.Handler`

You fill in the blanks, aka business logic.

### Spec generation

### Interaction with a Swagger API

Postman

SoapUI

commandcar for instant CLI access

### Some resources

go-swagger documentation

Swagger Editor

Swagger UI

Swagger Hub (collaboration space)

Specification

Open API Initiative

Documentation and testconsoles for 175 APIs

### What's next?

go-swagger going forward:

- embrace http/2 entirely
- integrate with swagger-codegen
- stub generation
- test generation
- integration testing
- httpie like CLI generation with optional syntax highlighting
- more transports
- scriptable handlers
- more wireformats like protobuf, msgpack, ...

### Thank you

Ivan Porto Carrero

VMware

https://github.com/casualjim

@casualjim

Use the left and right arrow keys or click the left and right edges of the page to navigate between slides.
(Press 'H' or navigate to hide this message.)