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/httpstyle middleware: `func(http.Handler) http.Handler`
You fill in the blanks, aka business logic.
Spec generation
Interaction with a Swagger API
commandcar for instant CLI access
Some resources
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