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.
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