Swagger is much more than just a way to describe RESTful APIs. It is a powerful collection of tools that works across an entire stack—from interactive documentation to SDK generation and server-side code. Join us in this webcast for a technical deep-dive into how Apigee worked with the Swagger community to build the Swagger Editor. This open source web app lets you design APIs using YAML and simultaneously preview their documentation, right in your browser. There's a lot of technology under the hood that makes this possible, and we also walk through the various stages of its development, including: - considering JavaScript frameworks - moving away from CoffeeScript - abstract syntax tree (AST) for error reporting, code completion, and navigation - form generation Join Apigee's Mohsen Azimi and Prabhat Jha to see how this powerful tool was built. Watch video: http://youtu.be/5xDVe-t6pnQ Download podcast: http://bit.ly/1zNS2cZ

1. Mohsen Azimi / Prabhat Jha
14 April 2015
Design and Implementation of the
Swagger Editor: Our Journey

2. Today’s speakers
Mohsen Azimi
@mohsen____
Prabhat Jha
@prabhtajha

3. © 2014 Apigee – For Public display
Apigee social channels
3
YouTube
http://youtube.com/apigee
Slideshare
http://slideshare.com/apigee
• https://community.apigee.com ©CC BY-SA

4. © 2014 Apigee – For Public display
Agenda
• Swagger intro
• The case for the Swagger Editor
• Demo
• Choosing underlying frameworks and tools
• Optimizing for performance and usability
• Q&A
©CC BY-SA

5. © 2014 Apigee – For Public display
Swagger intro
5
• API specification format
– deterministic and little opinionated, yet flexible
– language and platform independent
– ecosystem of 100K+ developers worldwide
– popular with both startups and large enterprises.
• Tools to:
– generate documentation
– generate API specs from code
– generate client SDKs (JS, iOS, Android, Java, ….)
• Tons of community contributed projects, including a few from Apigee.
https://github.com/swagger-api/swagger-spec#additional-libraries
©CC BY-SA

6. Spec first or code first?
6©CC BY-SA

7. Spec first or code first?
7©CC BY-SA

8. © 2014 Apigee – For Public display
Swagger 2.0
8
• Single file for specification
• More JSON schema
• Introduction of JSON references
• Markdown support for descriptions
• JSON schema for validating Swagger 2.0 specs
• YAML as first-class citizen—more human friendly
• Lessons learned from Swagger 1.2 and previous versions
©CC BY-SA

9. © 2014 Apigee – For Public display
Sample API definition
9
swagger: '2.0’
info:
version: 1.0.0
title: A simple API
paths:
/:
get:
responses:
200:
description: OK
{
"swagger":"2.0",
"info":{
"version":"1.0.0",
"title":"AsimpleAPI"
},
"paths":{
"/":{
"get":{
"responses":{
"200":{
"description":"OK"
}
}
}
}
}
}
YAML JSON
©CC BY-SA

10. © 2014 Apigee – For Public display 10
How should you build an API ?
©CC BY-SA

11. © 2014 Apigee – For Public display 11
How should you build an API anything?
©CC BY-SA

12. © 2014 Apigee – For Public display 12
How should you build an API anything?
Design it first !!
©CC BY-SA

13. © 2014 Apigee – For Public display
Design-first API development
13
• Fast feedback loop
• Well-structured API
• Collaborative development
• Well-documented API with users in mind
• Testable API
©CC BY-SA

14. © 2014 Apigee – For Public display
Good design requires good tools
14
©CC BY-SA

15. © 2014 Apigee – For Public display
Making the case for an editor
15
• There was no tool that provided a fast feedback loop for authoring
Swagger specs
• No one can remember all the Swagger specs (well, maybe some
can*)
• Other API specs have authoring tools
• To benefit quickly, help was needed with the transition from 1.2 to 2.0
* Benefit of the doubt given to @webron and @fehguy
©CC BY-SA

16. © 2014 Apigee – For Public display 16
» Short Demo
(http://editor.swagger.io)
©CC BY-SA

17. © 2014 Apigee – For Public display 17
» Let’s get to the nuts and bolts
http://azimi.me/presentations/building-swagger-editor/index.html#42
©CC BY-SA

18. Questions ??
Mohsen Azimi
@mohsen____
Prabhat Jha
@prabhtajha
• Try it live: http://editor.swagger.io/
• Open issues : https://github.com/swagger-api/swagger-editor
• More help: https://community.apigee.com/
©CC BY-SA

19. © 2014 Apigee – For Public display
Thank you
14 April 2015