This document discusses Swagger, a schema format for defining APIs in JSON, and its various tools like Swagger UI, Editor, and Codegen that facilitate API development. It highlights the need for programmatic solutions to generate accurate API structure while maintaining documentation, and introduces a tool called swagger2postman for converting Swagger JSON into Postman collections. Additionally, it suggests standardizing Swagger documentation across APIs for better onboarding and integration testing of new developers.

1. Adding Swagger to your API
Joe Conley

2. What is Swagger?
A schema to define your API in JSON format
That‘s it!

3. Why Swagger?
The nice folks at Swagger have created some fancy tools
based on your API‘s JSON schema.
Swagger UI – LIVE and INTERACTIVE documentation
based on your schema
Swagger Editor – Use a live YAML editor to build your
schema
Swagger Codegen – dozens of libraries for different
languages will generate code stubs based on your
schema
Plus an entire ecosystem of tools which will help you
generate your API schema

4. Demo – C.U.B.E., Upsell Reporting

5. TODO: Make More Programmatic
As of now the CUBE JSON was mostly handwritten, with a simple
Handlebars converter to insert values from the config.
Ideally we‘d like to build a library that‘s minimally invasive to our code but
powerful enough to detect the structure of our API, and still let us add
metadata like plaintext descriptions.
Possible Solutions
- Annotations? It‘s a nightmare in Play.
- Reflection?
- Macros?

6. Aside: Syncing with Postman
I get the sense some people here use Postman? Me too!
Swagger UI is nice for some basic testing and operations, but
if you need to have greater control over your HTTP requests or
quickly switch environments, Swagger UI won‘t cut it.
But it‘d still be nice to stay in sync with our JSON API schema.
Well it turns out that Postman stores their collection information
in JSON as well
So…..

7. Shameless plug: swagger2postman
Simple transformation of a Swagger JSON API schema into a
Postman collection.
I ran into this problem with a previous client. It‘s a simple Scala
program which converts valid Swagger 1.2/2.0 JSON spec and
returns a valid Postman collection in JSON that you can import
directly into Postman.
Note: Postman has an import from Swagger function, but (at the
time I wrote this) it wasn‘t very good.
Github: https://github.com/josephpconley/swagger2postman
App: http://app.josephpconley.com/swagger2postman
TODO automate this?

8. Discuss: Standardize on Swagger?
I‘ll admit I was surprised none of the APIs had some form of
standard documentation.
Would it be valuable get all the APIs we use on some basic Swagger
documentation? At least the V2 Resource servers?
Would make easier onboarding of new devs!
Requires additional effort to maintain regardless of how it‘s
implemented
Could also lead to other optimizations too. I worked on an API test
framework for a client built using JSON specs, we could conceivably
automate the integration testing of an API with help from the
Swagger Spec

9. Questions? Comments?

10. Questions? Comments?