DESIGn-FIRST APIs
with OPen API Spec (OAS)
nanovazquez.dev
@nanovazquez__
In most projects, the biggest challenge to solve is not technology, it's communication
USEFUL LINKS
Full-stack developer (15+ years)
International speaker
Engineering manager @ MODO
Microsoft MVP & Co-organizer of conferences & meetups
ReactBA, vOpen, DevDayAr
HI! I'm Nano Vazquez
Today's Agenda
#1
Writing your first OAS Document
#2
Implementing your oas API
#3
DEVELOPING API CLIENTS for your consumers
SCENARIO
WHAT WE ARE GOING TO DO
THe team
Use cases
?
200 OK- List of speakers of any conference
- List of activities of any conference
- The agenda of a conference
- Ability to provide feedback to any activity
Hey, can you send me the docs of your service?
?
200 OK
No docs
Nah, Just use it
CODE AS DOCS
My code doesn't need docs
AD-HOC DOCS
This just came fresh out of the oven
AD-HOC DOCS
No docs
CODE AS DOCS
#1
#2
#3
SUMMARY
is there a better way?
Idea: API Portal
WRITING YOUR FIRST OAS DOCUMENT
Swagger
Swagger is an open source software framework backed by a broad ecosystem of tools that helps developers design, build, document, standardize and consume RESTful Web services.
Automated documentation
Code generation
Test case generation
OAS
Use cases
?
200 OK- List of speakers of any conference
- List of activities of any conference
- The agenda of a conference
- Ability to provide feedback to any activity
DEMO 1: YOUR FIRST OAS DOC
Swaggerhub
REcap: SWAGGERHUB
web-based editor with autocomplete
#1
#2
#3
Real-time autogenerated API docs
An API Auto Mocking integration
DEMO 2: TEST YOUR API
TEST YOUR API
DEVELOPING
API CLIENTS
CONFIGURE CLIENT SDK
DEMO 3: THE CLIENT SDK
THE clIENT SDK
CLIENT SDK LANGUAGES
30+ languages
CLIENT SDK LIFECYCLE
REcap: Client SDK
AUTOGENERATED LIBRARIES TO SIMPLIFY USAGE
#1
#2
#3
Multiple languages SUPPORTED
DELIVERED VIA PACKAGE MANAGERS
IMPLEMENTING YOUR API
IMPLEMENT AN API
DEMO 4: Server STUB
DOWNLOAD THE SERVER STUB
API DOCUMENTATION
SUMMARY
#1
WRITE YOUR OAS DOCUMENT FIRST
#2
PROFIT!
#3
GET CLIENT SDK, docs AND SERVER STUB FOr free
well... no, implement it :D
enabling others to code right away
Twitter: @nanovazquez__