“The OpenAPI specification, which is formerly known as Swagger Specification, is a community-driven open standard, programming language-agnostic interface description for HTTP APIs. This allows both humans and computers to discover and understand the capabilities of a service without requiring access to the source code.”
Because AppMap records your code’s runtime behavior, it can see and record all of the HTTP API calls processed including the schema of each request and response. Creating OpenAPI definitions by hand is error prone and time consuming. Keeping them up to date is additional work that quickly falls out of sync with the code. Using the AppMap we can automatically output OpenAPI definitions for an application.
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.
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.
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.
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.
Refer to the AppMap integrations documentation to learn more about how to integrate your OpenAPI documentation with other 3rd party software and services.
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