In my last post, I introduced you to the REST Connector and how you can generate connectivity using an OpenAPI Specification. In this post, we’ll get to know the specification a little better, and introduce some great Swagger productivity tools.
Why get to know OAS?
Maybe you already have a specification, but want to modify it! Not all the specs I’ve seen actually validated successfully – so I needed to modify them before using them. Or, maybe you don’t have a specification and want to build one to support custom REST calls. Both are great use-cases, and much easier than you may think!
How I approach OAS
- Swagger Tools
Swagger offers a number of great products, and they’re all basically free to use. The Swagger UI is an intuitive way to visualize and test API methods (live demo here). But, the Swagger Editor includes the specification text and the UI all-in-one!
Swagger Editor is where I spend most of my time: http://editor.swagger.io/#
- JSON or YAML:
OpenAPI Specs can be documented in JSON or YAML. At the time of writing this, Scribe’s REST Connector only reads from JSON – but it’s very easy to convert between the two, especially in the Swagger Editor.
When I’m editing a spec, I use YAML. There’s less to write, and you’re not opening and closing quotes or curly braces:
This API spec for Uber only has 5 methods but is described in a total of 374 JSON lines vs. 266 YAML lines – and not to mention, the Swagger Editor has better intelli-sense and styling for YAML.
I spend most of my time working in YAML and then saving as JSON.
- Defining what you need
OAS covers almost everything in a RESTful API. And there is a method to the madness; I found a nice site to help you ‘map’ from Handyman out where to define the properties of your API calls:
Screenshot of the Open API from API Handyman
Check out this interactive mapper, here: http://openapi-map.apihandyman.io/?version=2.0
Minimal specs are going to look like the following:
If you’re completely new to Swagger, use this minimal spec to play around and get started.
Cross-Origin Resource Sharing (CORS) is a technique to prevent websites from doing bad things with your personal data, and most browsers are going to enforce it. You don’t need to be expert on CORS to use Scribe’s REST Connector, but occasionally, you might need to enable CORS on your browser to use the Swagger Editor’s “Try it Out” feature.
I spend a lot of time testing API calls in the Swagger Editor, and I need to have CORS setup to do that.
Common Errors from Swagger Editor that are probably caused by CORS:
- Code: Undocumented
- Details: TypeError: Failed to fetch
- Details: TypeError: Cannot read property ‘xyz’ of undefined
Setting up CORS:
You can just add these extensions to your browser:
- Google Chrome: https://chrome.google.com/webstore/detail/allow-control-allow-origi/nlfbmbojpeacfghkpbjhddihlkkiljbi?hl=en
- Mozilla Firefox: https://addons.mozilla.org/en-US/firefox/addon/cors-everywhere/
Just make sure you turn off the CORS plug-in when you’re not in the Swagger Editor 🙂
Other productivity tools:
- Start saving and sharing your Specs with SwaggerHub: https://app.swaggerhub.com/search
- Convert those Postman Collections to Swagger 2.0 with APIMATIC: https://apimatic.io/transformer
- Convert API JSON Body/Responses using the Swagger Toolbox: https://swagger-toolbox.firebaseapp.com/#
- OpenAPI map: http://openapi-map.apihandyman.io/?version=2.0
- Sample OpenAPI specs: https://apis.guru/browse-apis/
Now that you have an overview of the Spec and the Tools, go learn-by-doing! Build a spec and test it out in the Swagger Editor. In my next post, we’ll connect to your spec in Scribe.
- Connecting with Scribe REST Connector
- Common integration patterns with REST