❗️

Deprecated command

We no longer actively support this command. We recommend you use apidump instead and integrate Akita with your active traffic.

The apispec command transforms traces into OpenAPI3 specifications annotated with additional information, like data formats.

# Creating a spec from a trace in the Akita Cloud:
akita apispec --traces akita://myService:trace:traceName \
  --out akita://myService:spec:specName

# Creating a spec from a trace stored in the local file system:
akita apispec --service myService --traces path/to/traceName.har \
  --out path/to/specTarget.yaml

Specs created in the Akita Cloud will be located in the service specified in the AkitaURI. For specs output locally, a copy will also be created in the service given in the --service flag.

--traces

Use the --traces flag to choose one or more traces to build a spec from. Each argument is either a path to a trace file in the local file system or an AkitaURI referencing a trace located in the Akita Cloud.

--trace-tag key=value

Specify a tag of the form key=value to select the most recent trace that has a matching trace. See Parallel Learning for instructions on using this option to create a model from a distributed trace.

--out

The --out flag identifies the target location to create the spec and can be a local file path or an AkitaURI.

The special value --out - prints the spec to stdout.

By default, if --out is not present, then the spec will be assigned an auto-generated name and stored in the Akita Cloud in the service supplied in the --service flag. In this case, the --service flag is required.

Optional Flags

Removing Unnecessary Endpoints

As you collect traffic traces and generate specs, you might find that your traces (and therefore specs) contain extra traffic not part of your API. For example, suppose your service exposes an API but also serves static resources, like images, JavaScript files, font families, and so on.

You can use the --path-exclusions flag to avoid including these requests in your spec. Continuing with the example, here's how you would omit JPEG, PNG, and JavaScript files.

akita apispec --traces akita://myService:trace:myTrace \
  --out akita://myService:spec:prunedSpec \
  --path-exclusions '*.jpg,*.png,*.js'

Adding and Removing Path Parameters

Akita automatically infers path parameters based on API traffic. For example, a trace might contain two requests with two different user IDs in the path.

# Requests
GET /api/v1/users/usr_134819/friends
GET /api/v1/users/usr_999999/friends

# Inferred Endpoint
GET /api/v1/users/{arg4}/friends

However, sometimes Akita gets it wrong. In that case, you can force specific positions in paths to be (or not to be) path parameters.

📘

Likely Cause of Missing Path Parameters: Too Few Requests

Akita infers path parameters by comparing similar requests. In the example above, only the User ID differed in the path, and the shapes of the requests and responses are similar, making it likely that the User ID segment is a path parameter.

However, if Akita only sees one request to an endpoint, it won't have enough information to generalize path parameters.

A path prefix pattern identifies one or more positions in a path as having (or not having) a path parameter. Paths, in this case, are made up of path segments separated by /.

In a path prefix pattern, each segment is either a string, a path parameter ({parameter_name}), or a placeholder ^ that indicates that the segment should not be generalized into a path parameter.

Here are a few examples.

Example 1: Simple Prefix Match

--path-parameters /v1/users/{user}

Example 2: Longest Prefix Match

When you add more than one prefix pattern, the longest prefix match gets applied.

--path-parameters /v1/users/{user},/v1/users/{user}/projects/{project}

Example 3: Removing a Path Parameter

Sometimes, Akita infers a path parameter where none exists. As a result, different paths are incorrectly collapsed into the same endpoint. The ^ character indicates that a given segment should not be a path parameter.

--path-parameters /v1/^

GitHub and CI Integration

When adding Akita to a CI/CD pipeline, you will need to indicate the GitHub branch, commit hash, pull request number, and repository name. This lets Akita publish a GitHub comment to your PR summarizing any API differences introduced by the PR.

📘

CircleCI and Travis

If you use CircleCI or Travis for continuous integration, Akita's apispec command will automatically detect the relevant GitHub info from your environment. No need to use the --github-* flags.

When using these flags as part of CI to trigger a GitHub commit message, all flags are required.