OpenAPI Features

AppMaps, the data source that’s used by AppMap OpenAPI, contain runtime traces of application code. Since the OpenAPI definitions generated from AppMap are built from recorded code execution, it shows the API “as it really is”. Here are some things you should know about how to generate OpenAPI definitions with AppMap.

Schema

The generated OpenAPI schema only includes information (paths, methods, status codes, parameters, responses, headers, security) that have actually been observed in the AppMap data. So, if a particular code behavior has not been observed by AppMap, it won’t be present in the OpenAPI.

When AppMap data is collected by running test cases, the generated OpenAPI will reflect the code coverage of the application with regard to its APIs. If an expected path, method, status or parameter is not observed in the generated OpenAPI, you’ll know it’s missing because it’s not tested.

Object schema is inferred from runtime data. When there are many examples of a request, the inferred schema of all the examples is merged into one unified schema.

Both request and response schema are available.

Use Cases

Pull Request Review

We suggest you generate OpenAPI for all new work, and commit the openapi.yaml file to source control. When a pull request contains API changes, a diff view of the OpenAPI changes is a very useful way for code reviewers to quickly get the “big picture” of the new branch.

Update Documentation Automatically

By generating OpenAPI definitions as part of your continuous integration process, you can ensure that your documentation continually updates automatically as the code updates. This reduces unnecessary engineering toil working to keep documentation up to date manually.

Send to 3rd Party Services

Integrate AppMap OpenAPI generation with various 3rd party services to share OpenAPI documentation with your end users or validate and diff changes over time. Refer to the documentation to learn how to incorporate AppMap OpenAPI generation with various 3rd party services.

Customization

Operation summary

To populate operation.summary, set the header X-OpenAPI-Summary in your response.

Example

Ruby on Rails Controller

class AccountActivationsController < ApplicationController
  def edit
    response.headers['X-OpenAPI-Summary'] = 'Activate the account of an existing user'

openapi.yaml

/account_activations/{id}/edit:
    get:
      responses:
        '302':
          content: {}
          description: Found
      parameters:
        - name: email
          in: query
          schema:
            type: string
        - name: id
          in: path
          schema:
            type: string
          required: true
      summary: Activate the account of an existing user