APIClarity: Reconstructing an OpenAPI Specification

Anne McCormick

Wednesday, April 5th, 2023

6 min read

This blog is part of the APIClarity How-To Series.

Reconstructing an OpenAPI Specification

In this blog, I’ll show you how APIClarity can reconstruct an OpenAPI spec based on observed API traffic for an application. To recap, an OpenAPI spec is used to compare incoming API traffic against what’s expected and allowed. An OpenAPI spec can either be uploaded, or APIClarity can reconstruct one, which is what we’ll cover here. 

Note that API traffic has to be flowing for your application in order to be observed. Without API traffic, APIClarity cannot reconstruct an OpenAPI spec. 

Behind the Scenes 

Throughout the APIClarity blog series, we’ve been using Sock Shop as our sample microservice application. See the installation blog for specifics on setting up APIClarity with Sock Shop.

In a previous blog, we went through the steps of uploading an OpenAPI spec for the catalogue microservice in the Sock Shop demo application. For our purposes here, let’s pretend like the OpenAPI spec doesn’t exist yet for the Sock Shop catalogue application, and let APIClarity reconstruct it. 

Reconstruct the Spec 

In the APIClarity UI, go to the API Inventory tab on the left in the dashboard UI (circled in green in Figure 1). 

Figure 1: Choose API Inventory Tab From Dashboard UI

In the API inventory list, select the one for your microservice application. In this case, we’ll select “catalogue.sock-shop” (circled in green in Figure 2). 

Figure 2: Select “catalogue.sock-shop” from API Inventory

On the next screen, select the Reconstructed tab (circled in green in Figure 3) to see the API endpoints for the application that were reconstructed by APIClarity from observed traffic.

Figure 3: Choose Reconstructed Tab

Reconstructed OpenAPI specs need to be reviewed and approved by the user before they can be used for comparison with incoming traffic. On the next screen, click “Review” to see the observed API endpoints (see Figure 4). 

Figure 4: Click “Review” to see Reconstructed APIs

Next, you’ll see a listing of the various API endpoints that were observed. Note that the API parameter names are generic (e.g. “param1” in Figure 5). Let’s fix that. 

Figure 5: Observed API Endpoints

Click on the endpoint with the generic parameter name, and then the “Update Parameter Name” pulldown (Figure 6).

Figure 6: Update Parameter Name

We know that the parameter in this case is a catalogue ID, so let’s change the name to “id” (Figure 7). 

Figure 7: Change “param1” to “id”

Now, in the Spec Reviewer window, we’ll see the updated parameter name (Figure 8).

Figure 8: Updated Parameter Name (“id”)

Now that the API endpoints are updated, let’s approve them. Click the arrow next to “Pathto select all endpoints, then select Approve Review (both circled in green in Figure 9). 

Figure 9: Select all Endpoints then Click Approve Review

An Approve Review window will pop up asking us to approve the review and select the OAS (OpenAPI spec) version. Click the down arrow (Figure 10). 

Figure 10: Click Down Arrow on Approve Review UI

You’ll see OAS v2 and v3 as choices. Let’s go with the latest and greatest. Choose OAS V3 (Figure 11).

Figure 11: Choose OAS V3

Click Yes to approve the OpenAPI V3 spec version of this API (Figure 12). 

Figure 12: Click Yes button to Generate Reconstructed Spec

Now that the reconstructed spec is approved, we’ll see the API inventory listing in the APIClarity UI. Click on “default-tag” (Figure 13). 

Figure 13: Click “default-tag”

We’ll now see the listing of approved API endpoints for the catalogue application. This is very similar to what we saw for the upload API spec example in the prior blog, but with a notable difference. Here, only two catalogue API endpoints are listed, whereas in the uploaded API spec example, four were listed. This is highlighting a limitation of the spec reconstruction process – APIClarity can only include APIs that were observed. If some APIs (in this case two of them) were never called, APIClarity would not know about them, and thus would not include them in the reconstructed spec. After the reconstructed spec is approved, if those two missing APIs were called, they would be reported as shadow APIs (i.e. undocumented API calls). They could then be added to the approved spec if desired. We’ll cover shadow APIs in a future blog. 

Click the arrow next to one of the endpoints (Figure 14). 

Figure 14: Browse Reconstructed API Endpoints

If you click on a particular endpoint, you’ll see a “hit count” graph of the number of times the API has been called. 

Figure 15: API Endpoint “Hit Count”

To see the API spec in Swagger, click on “see on Swagger(circled in green in Figure 16).

Figure 16: Click “see on Swagger”

Each API endpoint is listed in Swagger (Figure 17).  

Figure 17: Swagger UI Listing API Endpoints

Click on each endpoint to see example request parameters and an example response. 

Figure 18: Swagger UI API Endpoint Parameters

At the bottom, in the Schemas pane, each API response schema is provided. 

Figure 19: Swagger UI Schemas Detail

Download the Spec 

Now that we have an approved OpenAPI spec for our application, we can download it. On the Swagger UI, up at the top, there’s a link to download a JSON file for the reconstructed OpenAPI spec (circled in green in Figure 20). 

Figure 20: Link to Reconstructed Spec in Swagger UI

Spec Differences 

Similar to how spec differences can be detected between observed API traffic and an uploaded OpenAPI spec, they can also be detected with a reconstructed/approved spec. See here for an example spec difference that was flagged. 


Congrats, you have now reconstructed an OpenAPI spec with APIClarity! 

Next up in the blog series: Detecting Shadow APIs. 

Anne McCormick is a cloud architect and open-source advocate in Cisco’s Emerging Technology & Incubation organization.