Developer Candy: Swagger-UI for the Patentsview api

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

Note: This article is about using Swagger UI with the original version of the Patentsview API (which is currently planned to be shutdown February 12, 2025). The Patentsview API team has created a Swagger UI page for the new version of the API but it requires an API key.

Pretend, for a moment, that you are a developer working on something cool that needs to call an API. If you are lucky, the API 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 an API 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 or yaml object that specifies everything 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 a json or yaml object and plug it into the Swagger-UI package they've downloaded from swagger.io. That's nothing more than copying a text file containing their json or yaml object and Swagger-UI's dist folder to their web site. Then they just need to update the index.html file in the dist folder with the URL of the text file containing their json or yaml object and boom, their web site has a Swagger-UI web page for the whole world to use!

Russ noticed that the original version of 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, a Get request is sent to the API's endpoint with the parameters that were entered and its response is added to the Swagger-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 a useful error message 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 data the API returned, nicely formatted for humans to read (the API may have sent it back without the indenting that shows the data's structure).



The Swagger-UI web page and this API's error messages 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!

Naturally, you will want to create a swagger object for your API, all the cool APIs have them. There are a couple of ways to do this, some are easier than other and luckily there are tools to help you. The best way, though probably the most difficult to do retoractively, is to bake it into your API. That is, put swagger annotations in your source code so your swagger object is generated at runtime, ensuring that your Swagger-UI page always matches your code (assuming you add or edit annotations when making code changes). This is a great idea if you are planning to develop a new API. There are annotations available as opensource projects for a number of different programming languages, like java and php. Odds are there is one for the language your API will be written in.

There is a free editor at https://editor.swagger.io/ that would help you create a swagger object from scratch. It also lets you edit an existing swagger object graphically, either from a URL or from a file you uploaded. (Note that if you want to import a swagger object via an http: URL, you need to access the editor over http: instead of https:, http://editor.swagger.io/ Also note that Importing a URL may not work if the provider doesn't not allow CORS requests. You can always downlod the file and then upload the file into the editor to get around this.) Once your swagger object is how you want it, you can click the editor's Generate Clients and Generate Servers links to have the it generate code for you. Take a minute or two to let your head stop spinning before you try to do anything else. If the swagger object you are editing is a version 2 object, you can have the editor try to convert it to Swagger 3, also knowns as OpenApi 3 (under the Edit menu). It can be useful to have both a version 2 and version 3 swagger object for an API, as will become clear in just a bit.

Smartbear, the original creators of Swagger, offers tools, some of which cost money to access, to help you create your swagger object. Also helpful is roger13's SwagDefGen which converts sample json into its corresponding swagger object definition that you can copy and paste into a file to create your swagger object. You still need to add your endpoints etc. but it helps relieve some of the tedium associated with creating a swagger object from scratch, plus it's free. There is also this Swagger-UI page that explains swagger objects! You've got to admire the creativity that went into that. It uses the ubiquitous pet store API's swagger object by default, but the green bar at the top of the page would let you enter the URL of any swagger object. (If you hit that page over http:, it redirects to https: so your swagger object's URL has to be https: for it to work.)

A swagger object can also open doors in the opensource community. Several opensource projects take a swagger object as input to do something useful. The openapi-generator generates skeleton clients or servers for a dizzying number of packages (simliar, but more powerful that what the swagger editor does). Russ used the Openapi Generator to create html documentation from the Swagger/OpenAPI json object for the new version of the patentsview API. Here are two different web pages, html and html2, both generated from the same object, using two different sets of templates. (Similar to the Swagger editor's Generate client html or html2.) The documentation can be easily regenerated as the Swagger/OpenAPI object changes. Even more opensource projects are listed at http://openapi.tools in a nicely formatted list showing which version(s) they accept as input.

There is also a methodology where you develop your swagger object first, before writing any code. You can pass around the swagger object or its not-yet-working Swagger-UI page for review and coding wouldn't start until everyone is happy with it. Russ has done that and then used the opensource openapi-generator to generate annotated java that produces the swagger object dynamically at runtime, insuring that his Swagger-UI page always matches his stellar code.

Oh, and if Russ hasn't sold you on the power of a swagger object, he suggests that you try importing it into Postman to see what happens: Boom, nicely loaded Postman collection just itching to hit the Patentsview API's endpoints for you! In Postman: File -> Import -> Import From Link [Swagger (v1/v2)] https://mustberuss.github.io/Patentsview-Swagger/patentsview.json

Update: for the new version of the API, import https://search.patentsview.org/static/openapi.json and set a global variable named PVIEW_KEY to the value of your API key. Then set an auth header in the imported collection as shown.

Russ would like to contribute the OpenAPI objects for the original version of the API and the new one to the Patentsview API project, should its developers care to host Swagger-UI pages at patentsview.org.

Update: Russ did contribute the two OpenAPI definitions!