Developer Candy: Swagger UI for the patentsview api

Russ Allen, developer and patent enthusiast, created a Swagger UI json object and explains its usefulness.

Pretend for a moment that you are a developer working on something cool that needs to call a web service. If you are lucky, the web service provider will have made a Swagger UI web page available for you. It's an opensource project that generates a web page that lets users make calls to the web service by filling in form fields. It's similar to Postman with a lot of setup work done for you. At the heart of Swagger UI is a json object that specifies all the api does or will do if you play by its rules (properly use its verbs and endpoints by passing what it expects in the formats it accepts). All an api provider needs to do is to create the json object and plug it into the Swagger UI package they've downloaded from swagger.io. That's nothing more than copying the json object and dist folder to their web site. Then they just need to update the index.html file with the url of the file containing their json object and boom, their web site has a Swagger UI web page for the whole world to use!

Russ noticed that the patentsview api did not have a Swagger UI web page so he created the necessary json object. Below is an example that shows both the power of the patentsview api and of Swagger UI. We start by filling in the Swagger UI web page's form fields that will issue a get to the patentsview's /patents/query endpoint but we intentionally made a mistake, perhaps you'll be able to spot it.

When we press the Execute button in the Swagger UI web page, the response is added to the UI page.

It seems we've made the api mad by requesting a field in the f parameter that it doesn't yet support. Fortunately for us, the patentsview api developers thoughtfully return an x-status-reason response header explaining exactly why it returned a 400 or Bad Request response code. How cool is that? (Note that not all api providers go to this extent to be helpful.) If we correct our request and press the Execute button again, we are rewarded with the api's data returned nicely formatted.


The Swagger UI web page and this api's x-status-reason become a powerful tool for developers and interacting with the api is a great way to quickly learn the ins and outs of the api before writing any code. Try this very demo here!

The json object can also open doors in the opensource community. Several opensource projects use the json object as input and generate skeleton clients or servers for a dizzying number of packages. Like many things in life, there are two standards. There's the Swagger 2.0 specification and the newer Swagger 3.0, also known as the OpenAPI specification. Russ used one of these opensource projects to convert the Swagger 2.0 json object into its corresponding Swagger 3.0/OpenAPI object. Having both versions maximizes usefulness. Some opensource projects accept either version but there are ones looking for a specific version. Try out the online swagger object editor at http://editor.swagger.io (note that at https: the editor would not be able to import our swagger objects from our http: urls.) Once you are in the editor, do a File - > Import URL of the 2.0 version at http://patentsview.historicip.com/patentsview.json. Then click the Generate Clients and Generate Servers links. When your head stops spinning, import the Swagger 3.0/OpenAPI object from http://patentsview.historicip.com/patentsviewswagger3.json and repeat the clicks on the generate links. Even more opensource projects are listed at http://openapi.tools in a nicely formatted list showing which version(s) they accept as input. Oh, and if Russ hasn't sold you on the power of the json object, he suggests that you try importing it into Postman to see what happens: Boom, nicely loaded Postman page just itching to hit the patentsview api's endpoints for you! In Postman: File -> Import -> Import From Link [Swagger (v1/v2)] http://patentsview.historicip.com/patentsview.json

Russ would like to contribute the two json objects to the patentsview api project if its developers would care to host a Swagger UI page at patentsview.org. Otherwise, the patentsview Swagger 2.0 UI page is available at http://patentsview.historicip.com/swagger/ and the Swagger 3.0/OpenAPI version is at http://patentsview.historicip.com/swagger3/. The UI pages look the same, but the underlying json objects are distinct and correspond to their respective Swagger versions.

Note: Currently the X-Status-Reason header is not being displayed in either version of the UI (in chrome at least). I've opened an issue to address this.