A Tour of Swagger for APIs
•Download as PPT, PDF•
6 likes•2,895 views
The document discusses Swagger, which is a specification and set of tools for describing and documenting REST APIs. It describes Swagger as both an API documentation framework and a specification that can help produce, consume, and visualize APIs. The document outlines different options for creating Swagger documentation, such as generating JSON from code annotations, manually writing JSON, or generating documentation at runtime from annotations. It also provides an overview of several Swagger tools and components and discusses when Swagger may or may not be suitable for a given situation.
Recommended
More Related Content
What's hot
What's hot (20)
Viewers also liked
Viewers also liked (14)
Similar to A Tour of Swagger for APIs
Similar to A Tour of Swagger for APIs (20)
Recently uploaded
Recently uploaded (20)
A Tour of Swagger for APIs
- 1. A tour of Swagger for (REST) APIs Allen Dean Information Development, IBM Watson™ #stc15
- 2. Swagger is API documentation Right? © 2015 International Business Machines Corporation 2
- 3. Well yes. But, just one of the tools… …called Swagger UI © 2015 International Business Machines Corporation 3
- 4. Swagger is a specification… …for describing a REST API © 2015 International Business Machines Corporation 4
- 5. And Swagger is a… …set of core tools © 2015 International Business Machines Corporation 5
- 6. And more tools… © 2015 International Business Machines Corporation 6
- 7. © 2015 International Business Machines Corporation 7 A robust community
- 8. Lots of support… …through community tools • Projects by languages: • Clojure, Go, Java, JavaScript, .Net, Node.js, PERL, PHP, Python, Ruby.. • Projects by frameworks or platforms: • Angular.js, Apache (Ant, Maven, Wink), Django, Express, Flask, Gradle, Grunt, MongoDB, Spring… • Projects by types • Servers, clients, converters, generators, parsers, validators… © 2015 International Business Machines Corporation 8
- 9. • A framework that helps to produce and consume APIs and helps visualize. • A specification that helps describe and document them. © 2015 International Business Machines Corporation 9 A technology and a methodology
- 10. How do you start? © 2015 International Business Machines Corporation 10
- 11. © 2015 International Business Machines Corporation 11 Decide how to create and deliver • Type of output • Online and hosted: Swagger UI (a JSON object) • File-based or offline: (HTML, markdown, etc.) • Method to create Swagger JSON • Generate from code (annotations) • Manually: write JSON by hand • Design and build: Swagger Node • When to generate from code • Build regularly • Create at run time
- 12. © 2015 International Business Machines Corporation 12 Type of output • Online: • Swagger UI runs in a web browser. • Not set up for printing or viewing offline • Static: HTML and other static outputs: • Swagger codegen • Generate the Swagger JSON and a simple HTML file • bootprint-swagger project • Swagger to HTML • Swagger2Markup project • Designed to integrate Swagger generated output with other API documentation
- 13. © 2015 International Business Machines Corporation 13 Decide how to create and deliver • Type of output • Online and hosted: Swagger UI (a JSON object) • File-based or offline: (HTML, markdown, etc.) • Method to create Swagger JSON • Generate from code (annotations) • Manually: write JSON by hand • Design and build: Swagger Node • When to generate from code • Build regularly • Create at run time
- 14. © 2015 International Business Machines Corporation 14 Write Swagger-compliant JSON
- 15. © 2015 International Business Machines Corporation 15 Manually create with Swagger Editor
- 16. © 2015 International Business Machines Corporation 16 Generate from annotations
- 17. © 2015 International Business Machines Corporation 17 Add Swagger to an existing API Find out what Swagger gives you for free: Annotate only your methods: @Api() and @ApiOperation annotations:
- 18. © 2015 International Business Machines Corporation 18 Hand-crafted JSON vs. annotations • Hand-craft: For when you don’t have access to the code • Annotations: Easier to maintain. More in sync. Developers can own or share • Characteristics: • Delivered online through the Swagger UI or converted to static • Generated from annotations or lovingly hand-crafted • Potential issues with hand crafting • "Oh the pain" of writing JSON • Docs in sync only as of last writing
- 19. © 2015 International Business Machines Corporation 19 Decide how to create and deliver • Type of output • Online and hosted: Swagger UI (a JSON object) • File-based or offline: (HTML, markdown, etc.) • Method to create Swagger JSON • Generate from code (annotations) • Manually: write JSON by hand • Design and build: Swagger Node • When to generate from code • Build regularly • Create at run time
- 20. © 2015 International Business Machines Corporation 20 Regularly built JSON For when you are not ready to generate at run time. •Characteristics: • Delivered online through the Swagger UI or converted to static • Generated from annotations •Potential issues • Docs in sync only as of last writing
- 21. © 2015 International Business Machines Corporation 21 JSON at run time Documentation is always in sync with the code •Characteristics: • Delivered online through the Swagger UI • Created from annotations • Generated at run time •Potential issues • Can be technically challenging
- 22. Survey of tools and components © 2015 International Business Machines Corporation 22
- 23. • JSON object • Can use YAML to construct it • Version 2 is current • Swagger UI is backward compatible with v1.2 © 2015 International Business Machines Corporation 23 Swagger-compliant file
- 24. © 2015 International Business Machines Corporation 24 Swagger UI Can run locally and display hosted APIs
- 25. © 2015 International Business Machines Corporation 25 Swagger Editor Can view a swagger file without the Swagger UI
- 26. © 2015 International Business Machines Corporation 26 Swagger-core annotations Output is swagger-compliant
- 27. © 2015 International Business Machines Corporation 27 Swagger-tools Showing validation from the CLI
- 28. © 2015 International Business Machines Corporation 28 Swagger.ed A visualization tool
- 29. © 2015 International Business Machines Corporation 29 Swagger-ed
- 30. Is Swagger for you? © 2015 International Business Machines Corporation 30
- 31. • Can generate reference docs from existing APIs • Useful in visualizing and testing your API • Easy to share • An active community (questions get answered, bugs get addressed, and features get added) • Works with a lot of languages, platforms, frameworks • Open source. Licensed under Apache • It has an API explorer © 2015 International Business Machines Corporation 31 Swagger is a good choice because…
- 32. • Your APIs are not good RESTful citizens • Swagger works best with REST • Your APIs are complex and Swagger might not be "expressive" enough • You don't like the look of the Swagger UI • Difficult to customize • It has an API explorer © 2015 International Business Machines Corporation 32 Swagger is not for you because…
- 33. Where to find out more Delivered by Swagger • Swagger website: http://swagger.io/ • Swagger demo: http://petstore.swagger.io/ • Swagger Editor: http://editor.swagger.io/ • Swagger Google Group: https://groups.google.com/forum/#! forum/swagger-swaggersocket • GitHub: https://github.com/swagger-api From others • Api Evangelist: Swagger: http://swagger.apievangelist.com/ • Swagger.ed: http://chefarchitect.github.io/apispo ts/swaggered/ • API Description Languages: Which is the Right One for Me? http://www.slideshare.net/SOA_Soft ware/api-description-languages- which-is-the-right-one-for-me © 2015 International Business Machines Corporation #stc15 33
- 34. Questions © 2015 International Business Machines Corporation 34
Editor's Notes
- Titles I thought about using: Help! My developers are using Swagger. Now what? What the heck is Swagger and why do I care? And you thought Swagger was an API doc tool... About me With IBM for 9 years, IBM Watson for 2. Watson was formed from the technology that was showcased on Jeopardy! In 2011. Before that, 10 years with tech startups. One right here: fourthchannel. Oh, and spent my elementary school years here back when Woody Hayes was in charge of the city. I really wanted to be the drum major for the marching band. If this doesn't make sense, I can't explain. Watson is focused on APIs and services. Over a dozen Watson services in the Watson Developer Cloud in the last year. The focus has driven some work around how we deliver the docs and what those docs are. No Eclipse info center or knowledge center. Me and Swagger: I learned about Swagger from one of my development teams. We were surveying how to provide an internal API explorer. We had hundreds of undocumented APIs and the dev team was sick of answering questions. We picked Swagger and I jumped on board. We retrofitted Swagger in those multi hundred APIs and I learned a lot about the process. Focus: In this presentation, I focus on the output of describing a REST API with Swagger. I'm not discussing various developer-centric topics, such as hooking Swagger up to your existing code, running Swagger, or generating servers or clients. What might be helpful to know about Swagger as an information developer so you can discuss it and use it.
- If you have seen Swagger, you're probably familiar with this look. And this IS Swagger to many people.
- But Swagger Swagger is more than this. This is the Swagger UI, the standard visualization of an API described by Swagger. And this is what most people think of when they hear Swagger. It's true that Swagger did start as a way for one company to help document their APIs. But Swagger is more than this visualization.
- Swagger is a definition language. A standard to help describe REST APIs for both humans and machines to understand. We're looking at a screenshot of the root specification for Swagger. The rules that Swagger tools understand. As information developers or content folks, we are often most interested in generating documentation and visualizations of the API so that humans can understand it. But because this has a structure can be used to validate a description, Swagger can be used throughout many parts of the lifecycle of a REST API.
- But there's more! Besides the Swagger UI, which you might see here, there are other tools that follow the spec and can be used with Swagger. Tools to help integrating swagger with code, and to help design and visualize APIs at the same time.
- And there are more tools to help create clients and servers Node express is now called Swagger node: GitHub: "tools for designing and building Swagger-compliant APIs entirely in Node.js." Parser: API Evangelist: "Parses a machine readable API definition and makes ready for use in specific language, structure, or platform."
- And Swagger has an active community on Google groups, an IRC channel, StackOverflow, and GitHub. The community answers questions from both developers and others. And they do suffer fools.
- You can write APIs in many languages and use in many frameworks. Swagger has support for many of them
- So, Swagger is both a technology and a methodology. The methodology is precise and consistent and allows the technology to work with it, often in automated ways (for example, creating clients and servers, supporting API explorers). Supports both bottom-up and top-down approaches. Can be part of much of the lifecycle of an API. Top down: help design and api, then create the code as well as produce documentation. Bottom up: Take existing API and add swagger annotations or create Swagger files separately. Lifecycle support: Design, Code, Text, Document.
- specific ways to think about putting this together for your set of APIs.
- Three things to think about: What kind of output do you want? Swagger UI runs online How are you going to get that Swagger file? And when to you generate that file?
- First up: what kind of output? We've seen the swagger UI. But what do you do when you want to hand the docs to someone who doesn't have access to the UI? What if you want to print? Then you have to look at other tools – some that come from Swagger and some from the community. Point is that creating these docs takes some additional work. Swagger codegen: A template-driven engine to generate client code in different languages by parsing your Swagger documentation. Not too familiar with bootprint-swagger Swagger2Markup converts a Swagger JSON or YAML file into AsciiDoc or Markdown documents which can be combined with hand-written documentation. The AsciiDoc documents can be converted into HTML5, PDF and EPUB. The Swagger2MarkupConverter supports the Swagger 1.2 and 2.0 specification. ID participation: you know the requirements for output.
- We've touched on how you create the Swagger file: by hand, including with the Swagger Editor, and with annotations
- Some of us love to code HTML by hand. Some to write DITA by hand. If you do, you'll love writing JSON by hand. Issues: how do you know that the JSON is valid? Use a good text editor, validate the JSON schema, use swagger-tools to validate semantically. Top down approach? This is design first – code flow from this Bottom up approach: Already have the API – add the Swagger descriptions to it.
- Hand crafting by using the Editor. Get validation for free. Although somewhat painful. Top down approach? This is design first – code flow from this You can also use the editor with Swagger Node to create the code as you design it. More for the developer in you.
- Annotations: generating Swagger output from your code. Has technical implications, but a good goal because it's easier to maintain and in synch. Bottom up approach: Already have the API – add the Swagger descriptions to it.
- JAX-RS annotations in red / Swagger annotations in blue You have to be comfortable reading the code, understanding a bit of what's going on. What's being sent. What's being returned. Our developers were very helpful getting me to a deeper understanding of how they put the APIs together. 2 Swagger annotations are required for Swagger to recognize an API: @Api for the resource (set of APIs) and @ApiOperation for the method (GET, POST, PUT, DELETE, etc.). Other annotations add details to the documentation. JAX-RS based applications can pull info from the basic @XxxxParam annotations (@QueryParam, @PathParam...), although you can override these
- May run some build process to generate JSON files served up to the web server - at which point you are still Annotation-based. Can also hand-code JSON - which seems like a terrifying commitment long term.
- This is a normal process for us with docs: write something, build or transform it, then deliver it (print/FTP it/copy files etc.) May run some build process to generate JSON files served up to the web server - at which point you are still Annotation-based.
- The ultimate in being in synch. Note that this is delivered through the Swagger UI, not offline. "Technically challenging" is an understatement. We did this with our first Swagger project. Was quite popular. But we had to caution users (internal) not to hang themselves by trying out delete operations, for example.
- Let's go through some parts of Swagger that you might use in documenting a REST API.
- We showed the JSON behind the Swagger UI. From the spec, "The files describing the RESTful API in accordance with the Swagger specification are represented as JSON objects and conform to the JSON standards. YAML, being a superset of JSON, can be used as well to represent a Swagger specification file." This is the JSON object. There is an excellent walkthrough of the swagger spec on the API Evangelist site: swagger.apievangelist.com. Have a link at the end of the presentation. The current Swagger UI can display both v2 and v1 compatible files, but not at the same time. V2 takes the form of a a single file and v1 is multiple files, so can't co-exist You can write this JSON.
- Common way to view Swagger-compliant JSON Standard visualization You can run the Swagger UI locally and display APIs that are hosted. You can host the Swagger UI Possible use for ID: own this!
- We also demoed this. Another way to view Swagger-compliant JSON Nice thing about the editor is that it's a quick way to view a swagger file without having access to the Swagger UI. Works with YAML. Accepts and saves JSON and YAML YAML is a recursive acronym: YAML Ain't Markup Language. From Wikipedia: Early in its development, YAML was said to mean "Yet Another Markup Language",[3] but it was then reinterpreted (backronyming the original acronym) to distinguish its purpose as data-oriented, rather than document markup. Designed to be easier for us humans to read and interpret. (Easier than JSON) Run online or locally (For example with Swagger Node) Possible use for ID: Update existing manually create specs. Take a different description (word doc) and write it up here)
- This is swagger in your code. The output of this is swagger-compliant and can be used in the Swagger UI This is a set of annotations to declare and manipulate the output. You don't need to know all about the Swagger spec, but you can use it as reference.
- Swagger is a spec. With this set of tools, you can check whether your JSON complies with the spec CLI Convert a file from v1 to v2 Validate a file: find errors and warnings. (Also possible in the editor). Showing this on screen. starts all Swagger document validation using the JSON Schema file(s). Once that validation passes, goes through each pertinent semantic validation. Possible use for ID: I often use this to help various teams validate their swagger – especially if they're creating by hand. Because I know the spec, I can help them describe their API while they focus on designing and coding.
- Have fun with visualization. This one is called Swagger.ed. Just an example of how different visualizations can be written against the same swagger-compliant files. Has a chrome extension
- Can zoom in and out Here I double-clicked on the pet path and can inspect the resource in a different visualization. Possible use for ID: review APIs for inconsistencies. Help teams visualize the catalog.
- Just a couple more slides
- Not only can you design APIs with swagger, you can add it to existing APIs. This is what we did in our first project. The Swagger UI can be excellent for finding inconsistencies and errors For example, once in Swagger, we noticed that identical parameters in different operations were different data types. One was a string, another an integer for the same thing. Also saw how inconsistent our resources endpoints were: mix of nouns and verbs. Mix of plurals and singulars Because it's a spec, you can share the description easily. If I give you a swagger-compliant file, you can load it in your swagger tool Lots of people are actively working on Swagger, both from a community standpoint and from a code standpoint Issues with commercial software? This is open source Has a great API explorer
- If your API endpoints aren't resources but actions. Lots of info crammed into a body request. Developers can get creative with APIs. Some are difficult to show. For example, showing that a query param could have value x or y, or z. Just recently supported. I work with people who don't like the look of Swagger UI. Think it's good as an API explorer, but not so good for reference. To modify the UI is tough, from what I understand. However, because it's a spec, you might be able to create your own visualization (think swagger.ed) Initial reactions were "cool!" Reactions from developers learning APIs has been mixed: "I like some other treatments better" Being cool is important. The "Try it" button has security implications. Some people also don't want it with their reference. Of course, you can always hide it.
- Show POC if have time: using docpad. Pull data from several sources and integrate