Creating OpenAPI specifications with Jargon

Jargon uses templates that let you quickly add or remove common API features

Jargon helps you create OpenAPI specifications from your domain models, and I’m going to show you just how quick and easy it is to do.

Each step of this process is available on the free tier of Jargon user — why not signup today and follow along.

The full domain that I’ve created for this guide, and it’s API specification, are available on Jargon, if you’d like skip ahead and see the finished product.

Modelling the ‘Swagger Petstore’

Firstly, you will need to create a domain model that describes the resources you would like your API to interact with, and importantly, the relationships between them.

I’ll be basing this API on the famous Swagger Petstore example. If you’re not familiar with it, the Swagger Petstore API describes a very simple store where you can buy pets — that’s about all you need to know about it to follow along.

The first step is to model the domain in Jargon. To speed the process up, and to have something to for a before-and-after comparison, I downloaded and imported the published specification.

Directly after the import, the data model looked like this:

The domain model, directly imported from the Swagger Petstore specification file

You can see the main resources, and some of their relationships to sub-resources, but it’s far from a complete picture. For example, there’s no link between Orders and Pets, or Customers and Users. There’s also quite a few mechanical resources, like _pet_post_Type and _pet_put_Type, which aren’t really very business-oriented.

I think we can do better.

The ‘Swagger Petstore’ — Jargon Edition

Here’s where I landed after tidying up the imported model:

Having a business-view of the petstore model helps people understand the entire domain - not just the schemas that are exposed in the API

Jargon helps you create a clear separation between the business view of the data and the technical details required to make it work. Removing the mechanical classes and joining up the resources results in a clear and simple view of all the data in a domain — not just the schemas described in the API.

The changes to get here weren’t major — but they do make a big difference. Here is what I changed:

• Removed the mechanical ‘_pet_put_Type’ style of classes
• Allowed an Order to be for a Pet
• Connecteded a Customer with their Orders
• Linked Users with Customers
• Picked which properties of each resource is it’s key

This last step is critical — not only is it important to explain to people how each part of the domain are identified, Jargon uses this information to construct your API paths.

Creating API paths from the model

Now we’ve got a model we’re happy with, we can stat describing the paths the API will have.

In Jargon, this happens by choosing a resource that will be the root and traversing your model’s relationships till you end up with the resource the path will operate on.

Here’s an example. Let’s say we wanted to show a Customer all of their Orders. Working backwards, we want to end up with an api path that looks something like this:

/customers/{customerId}/orders

Looking at our model, Customer has an array of Order, called orders, so that looks like the relationship to traverse.

Let’s create that path in Jargon.

In the upper right corner of the screen, is a button to toggle the path view. It looks like this:

Creating paths in Jargon happens in the same experience as creating the domain model.

Clicking it, then ‘Add an API path group’ will throw up a dialogue to select the root class for this group.

Jargon will only let you choose Entitys as roots. There’s a full guide on the different types of classes in Jargon, but if you haven’t read it — Entitys are classes that have their own identifier — and they are coloured blue.

You must choose a class that has an identifier as the root for your path.

You can also optionally add a prefix to the path, say if you wanted the final path to look something like:

/petstore/customers/{customerId}/orders

For now, we’ll just stick with Customer, and we’ll add a new path to this group. That brings up the path editor:

Jargon lets you easily walk through your model to create the API path, then choose what verbs it allows.

Let’s go though this screen bit-by-bit.

Up the top is where you identify the ultimate target for this path. If you were happy with the path operating on just the root (Customer in our example) you would leave the text box blank. If you wanted to target a sub-resource, start typing in the box, and Jargon will list the properties you can traverse.

In this example screen shot I’ve traversed from Customer through it’s orders property, which has a type of Order, and then through Order’s pet property.

Jargon will highlight the class type of each property, so you can easily see what they are — here, I can see that pet is an Entity, because it’s blue.

Immediately under the textbox, Jargon will tell me the Class we’re targeting — here it’s ‘Order[]’ — an array of Order.

The last part of this section is choosing if this path will operate on an individual resource, or a collection of resources. Given we want to list all the Orders, i’ve ticked this box.

The next section is where you would name an operation this path performs — if any. I won’t go into it here, but the final API specification I’ve generated contains operations like:

/pets/findByStatus

Because operations tend to do something, you can optionally choose to return a different type of resource from this path, instead of the one you’ve naturally targeted.

Finally, you can choose the verbs this path will support.

I’ve picked ‘GET’ — but others (specifically ‘POST’) will only target collections, and Jargon will fix that up for you in the specificaion you generate.

Once you’ve pressed save, you’ll be able to see the paths you’ve created for each group:

A list of all the paths for the Pet resource

Once you’ve got the paths you’re happy with, it’s time to generate the API specification.

Generating API Specifications

Open API specifications are what Jargon calls ‘Artefacts’ — things that are derrivded from a domain model. Now that we’ve got a model with paths, we can open up the API editor — which looks like this:

Jargon automatically infers the summary and operationId for each path, based on the resource type you’re targeting and verbs you’ve chosen.

On the left hand side, is all the paths that you’ve just created, but with one important and significant difference:

Jargon has inserted path segments for the identification properties of each resource you’re targeting along a path.

Because we identified which properties are the identifiers in the model, Jargon could work out which paths need identifiers, where they belong, and what they’re called. Jargon will also add descriptions for them in the path parameters section, drawing from the definitions you provided in the model.

I’ve glossed over a couple of steps, like where you choose which template to base this API specification on. In this example I’ve used the API design standards from the Australian Government, which includes things like standardised error reporting, and a couple of security headers.

Let’s take a look at how you include features from the templates:

Clicking on a path, will bring up that path’s details. The stuff up the top is pretty obvious — name, summary, description, etc. But down the bottom is where the contents from the template are populated. That looks like this:

Jargon API templates contain things like security details, canned responses, additional header information, and even standardised approaches to adding paging parameters.

Simply scroll through the list of what’s in the template, and click the bits you want to include. In this screen shot in particular, is where you can say this path supports paging — a way of breaking up the responses into smaller sections you can ‘page’ through — which adds standardised path query parameters to describe how paging works.

Navigating the API editor is pretty simple — click and expand the paths you would like to describe, fill in the details, and once you’re done — hit save.

Viewing your specification

Now you’re all done — you’ve modelled your domain, added paths, and included features from the template. All that’s left to do is see your specification.

They’re available from the artefacts tab of your domain’s detail page. You can either browse through it, or download it.

Your complete API specification, based on your model and the paths you created.

Wrapping up

So that’s how Jargon does API specifications.

Each step of this process I’ve shown above is available on the free tier of Jargon user — why not signup today and follow along.

The full domain that I’ve created for this guide, and it’s API specification, are available on Jargon.

If you haven’t already read them, there are a series of guides on using Jargon that you can read to learn more.