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 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 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 the json 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 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 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, 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 edit a swagger object via an http: url, you need to access the editor over http: instead of https:, http://editor.swagger.io/) 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 updated 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)] http://patentsview.historicip.com/patentsview.json
Russ would like to contribute the version 2 and 3 swagger objects to the Patentsview api project if its developers would care to host a Swagger-UI page at patentsview.org.
Update: Russ did contribute the two swagger/OpenAPI definitions!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/OpenAPI versions.
¹ The api also returns an X-Status-Reason header on a Bad Request but it is not being displayed in the Response Headers section (bottom of the image). Russ opened an issue to address this.