Migrate API server specification from Swagger 2.0 to OpenAPI 3.1

CHANGELOG.md

@@ -20,6 +20,8 @@ and this project adheres to
   [#4741](https://github.com/firecracker-microvm/firecracker/pull/4741),
   [#4746](https://github.com/firecracker-microvm/firecracker/pull/4746): Added
   official support for 6.1 microVM guest kernels.
+- [#4763](https://github.com/firecracker-microvm/firecracker/pull/4763): Migrated
+  API specification from Swagger 2.0 to OpenAPI 3.1.
 
 ### Changed
 

README.md

@@ -92,7 +92,7 @@ Firecracker's overall architecture is described in
 
 Firecracker consists of a single micro Virtual Machine Manager process that
 exposes an API endpoint to the host once started. The API is
-[specified in OpenAPI format](src/firecracker/swagger/firecracker.yaml). Read
+[specified in OpenAPI 3.1 format](src/firecracker/openapi/firecracker.yaml). Read
 more about it in the [API docs](docs/api_requests).
 
 The **API endpoint** can be used to:

SPECIFICATION.md

@@ -19,7 +19,7 @@ on the following:
    they are logged[^2] by the Firecracker process.
 1. **API Stability:** The API socket is always available and the API conforms to
    the in-tree
-   [Open API specification](src/firecracker/swagger/firecracker.yaml). API
+   [Open API specification](src/firecracker/openapi/firecracker.yaml). API
    failures are logged in the Firecracker log.
 1. **Overhead:** For a Firecracker virtual machine manager running a microVM
    with `1 CPUs and 128 MiB of RAM`, and a guest OS with the Firecracker-tuned

docs/api-change-runbook.md

@@ -143,19 +143,19 @@ conditions, there are 2 major cases where we need to deprecate an endpoint:
     but doing so immediately would be a breaking change.
   - We just mark the endpoint as deprecated.
 
-### Keeping Swagger updated
+### Keeping OpenAPI specification updated
 
 Make sure that any changes you make in the code are also reflected in the
-swagger specification.
+OpenAPI specification.
 
 Some tips:
 
-- There is nothing in the swagger file that shows whether an endpoint is
+- There is nothing in the OpenAPI file that shows whether an endpoint is
   mandatory or optional, it’s all code logic.
 - Mandatory fields in a request or response body are marked with
-  `required: true` in the swagger definition. All other fields are optional.
+  the `required` array. All other fields are optional.
 - If you need to redirect an endpoint, you have to clone the old one under the
-  new URI in the swagger specification.
+  new URI in the OpenAPI specification.
 
 ### Marking endpoints as deprecated
 
@@ -234,7 +234,7 @@ Firecracker API.
     deprecation case.
   - Add a unit test where you test your new code paths.
   - Fix all other failing unit tests.
-  - Update the swagger file to reflect the change, in this case by removing the
+  - Update the OpenAPI specification to reflect the change, in this case by removing the
     `vsock_id` field from the required parameter list in the `Vsock` definition
     and adding a description to it stating that it is deprecated since the
     current version.

docs/api_requests/actions.md

@@ -4,7 +4,7 @@ Firecracker microVMs can execute actions that can be triggered via `PUT`
 requests on the `/actions` resource.
 
 Details about the required fields can be found in the
-[swagger definition](../../src/firecracker/swagger/firecracker.yaml).
+[OpenAPI specification](../../src/firecracker/openapi/firecracker.yaml).
 
 ## InstanceStart
 

docs/api_requests/patch-network-interface.md

@@ -56,7 +56,7 @@ Accept: application/json
 ```
 
 The full specification of the data structures available for this call can be
-found in our [OpenAPI spec](../../src/firecracker/swagger/firecracker.yaml).
+found in our [OpenAPI spec](../../src/firecracker/openapi/firecracker.yaml).
 
 **Note**: The data provided for the update is merged with the existing data. In
 the above example, the RX rate limit is updated, but the TX rate limit remains

docs/device-api.md

@@ -33,9 +33,9 @@ BadRequest - HTTP response.
 
 ## Input Schema
 
-All input schema fields can be found in the [Swagger](https://swagger.io)
+All input schema fields can be found in the [OpenAPI](https://www.openapis.org/)
 specification:
-[firecracker.yaml](./../src/firecracker/swagger/firecracker.yaml).
+[firecracker.yaml](./../src/firecracker/openapi/firecracker.yaml).
 
 | Schema                    | Property              | keyboard | serial console | virtio-block | vhost-user-block | virtio-net | virtio-vsock | virtio-rng |
 | ------------------------- | --------------------- | :------: | :------------: | :----------: | :--------------: | :--------: | :----------: | :--------: |
@@ -108,9 +108,9 @@ virtio-block and virtio-rng devices.
 
 ## Output Schema
 
-All output schema fields can be found in the [Swagger](https://swagger.io)
+All output schema fields can be found in the [OpenAPI](https://www.openapis.org/)
 specification:
-[firecracker.yaml](./../src/firecracker/swagger/firecracker.yaml).
+[firecracker.yaml](./../src/firecracker/openapi/firecracker.yaml).
 
 | Schema                 | Property          | keyboard | serial console | virtio-block | vhost-user-block | virtio-net | virtio-vsock |
 | ---------------------- | ----------------- | :------: | :------------: | :----------: | :--------------: | :--------: | :----------: |
@@ -133,9 +133,9 @@ If more than 64 devices are configured for a VM in total on aarch64, only first
 
 ## Instance Actions
 
-All instance actions can be found in the [Swagger](https://swagger.io)
+All instance actions can be found in the [OpenAPI](https://www.openapis.org/)
 specification:
-[firecracker.yaml](./../src/firecracker/swagger/firecracker.yaml).
+[firecracker.yaml](./../src/firecracker/openapi/firecracker.yaml).
 
 | Action           | keyboard | serial console | virtio-block | vhost-user-block | virtio-net | virtio-vsock |
 | ---------------- | :------: | :------------: | :----------: | :--------------: | :--------: | :----------: |

docs/getting-started.md

@@ -311,7 +311,7 @@ configuration for the guest kernel and rootfs, all of the other resources are
 optional. This configuration method will also start the microVM, as such you
 need to specify all desired pre-boot configurable resources in the JSON. The
 names of the resources can be seen in \[`firecracker.yaml`\]
-(../src/firecracker/swagger/firecracker.yaml) and the names of their fields are
+(../src/firecracker/openapi/firecracker.yaml) and the names of their fields are
 the same that are used in the API requests.
 
 An example of configuration file is provided:

docs/logger.md

@@ -36,7 +36,7 @@ curl --unix-socket /tmp/firecracker.socket -i \
 ```
 
 Details about the required and optional fields can be found in the
-[swagger definition](../src/firecracker/swagger/firecracker.yaml).
+[OpenAPI specification](../src/firecracker/openapi/firecracker.yaml).
 
 ## Using command line parameters for configuration
 

docs/metrics.md

@@ -43,7 +43,7 @@ curl --unix-socket /tmp/firecracker.socket -i \
 ```
 
 Details about this configuration can be found in the
-[swagger definition](../src/firecracker/swagger/firecracker.yaml).
+[OpenAPI specification](../src/firecracker/openapi/firecracker.yaml).
 
 The metrics are written to the `metrics_path` in JSON format.
 

docs/mmds/mmds-design.md

@@ -116,7 +116,7 @@ reply.
 
 Somewhat confusingly, this is the name of the component which taps the device
 model. It has a user-configured IPv4 address (see
-[Firecracker MMDS configuration API](../../src/firecracker/swagger/firecracker.yaml))
+[Firecracker MMDS configuration API](../../src/firecracker/openapi/firecracker.yaml))
 and MAC (`06:01:23:45:67:01`) addresses. The latter is also used to respond to
 ARP requests. For every frame coming from the guest, the following steps take
 place:

docs/mmds/mmds-user-guide.md

@@ -15,12 +15,12 @@ two steps:
 1. Attach one (or more) network interfaces through an HTTP `PUT` request to
    `/network-interfaces/${MMDS_NET_IF}`. The full network configuration API can
    be found in the
-   [firecracker swagger file](../../src/firecracker/swagger/firecracker.yaml).
-1. Configure MMDS through an HTTP `PUT` request to `/mmds/config` resource and
+   [Firecracker OpenAPI specification](../../src/firecracker/openapi/firecracker.yaml).
+2. Configure MMDS through an HTTP `PUT` request to `/mmds/config` resource and
    include the IDs of the network interfaces that should allow forwarding
    requests to MMDS in the `network_interfaces` list. The complete MMDS API is
    described in the
-   [firecracker swagger file](../../src/firecracker/swagger/firecracker.yaml).
+   [Firecracker OpenAPI specification](../../src/firecracker/openapi/firecracker.yaml).
 
 ### Examples
 
@@ -115,7 +115,7 @@ structured in [JSON](https://tools.ietf.org/html/rfc7159) format. To replace
 existing metadata, a subsequent HTTP `PUT` request to the `/mmds` resource must
 be issued, using as a payload the new metadata. A complete description of
 metadata insertion firecracker API can be found in the
-[firecracker swagger file](../../src/firecracker/swagger/firecracker.yaml).
+[Firecracker OpenAPI specification](../../src/firecracker/openapi/firecracker.yaml).
 
 An example of an API request for inserting metadata is provided below:
 
@@ -150,7 +150,7 @@ To partially update existing metadata, an HTTP `PATCH` request to the `/mmds`
 resource has to be issued, using as a payload the metadata patch, as
 [JSON Merge Patch](https://tools.ietf.org/html/rfc7396) functionality describes.
 A complete description of updating metadata Firecracker API can be found in the
-[firecracker swagger file](../../src/firecracker/swagger/firecracker.yaml).
+[Firecracker OpenAPI specification](../../src/firecracker/openapi/firecracker.yaml).
 
 An example API for how to update existing metadata is offered below:
 
@@ -191,7 +191,7 @@ To retrieve existing MMDS metadata from host operating system, an HTTP `GET`
 request to the `/mmds` resource must be issued. The HTTP response returns the
 existing metadata, as a JSON formatted text. A complete description of
 retrieving metadata Firecracker API can be found in the
-[firecracker swagger file](../../src/firecracker/swagger/firecracker.yaml).
+[Firecracker OpenAPI specification](../../src/firecracker/openapi/firecracker.yaml).
 
 Below you can see how to retrieve metadata from the host:
 

docs/snapshotting/snapshot-support.md

@@ -271,7 +271,7 @@ curl --unix-socket /tmp/firecracker.socket -i \
 ```
 
 Details about the required and optional fields can be found in the
-[swagger definition](../../src/firecracker/swagger/firecracker.yaml).
+[OpenAPI specification](../../src/firecracker/openapi/firecracker.yaml).
 
 *Note*: If the files indicated by `snapshot_path` and `mem_file_path` don't
 exist at the specified paths, then they will be created right before generating
@@ -446,7 +446,7 @@ curl --unix-socket /tmp/firecracker.socket -i \
 ```
 
 Details about the required and optional fields can be found in the
-[swagger definition](../../src/firecracker/swagger/firecracker.yaml).
+[OpenAPI specification](../../src/firecracker/openapi/firecracker.yaml).
 
 **Prerequisites**: A full memory snapshot and a microVM state file **must** be
 provided. The disk backing files, network interfaces backing TAPs and/or vsock

src/vmm/src/logger/logging.rs

@@ -15,8 +15,8 @@ use utils::time::LocalTime;
 
 use super::metrics::{IncMetric, METRICS};
 
-/// Default level filter for logger matching the swagger specification
-/// (`src/firecracker/swagger/firecracker.yaml`).
+/// Default level filter for logger matching the OpenAPI specification
+/// (`src/firecracker/openapi/firecracker.yaml`).
 pub const DEFAULT_LEVEL: log::LevelFilter = log::LevelFilter::Info;
 /// Default instance id.
 pub const DEFAULT_INSTANCE_ID: &str = "anonymous-instance";
@@ -25,7 +25,7 @@ pub static INSTANCE_ID: OnceLock<String> = OnceLock::new();
 
 /// The logger.
 ///
-/// Default values matching the swagger specification (`src/firecracker/swagger/firecracker.yaml`).
+/// Default values matching the OpenAPI specification (`src/firecracker/openapi/firecracker.yaml`).
 pub static LOGGER: Logger = Logger(Mutex::new(LoggerConfiguration {
     target: None,
     filter: LogFilter { module: None },

tests/integration_tests/style/test_swagger.py

@@ -18,5 +18,5 @@ def test_firecracker_swagger():
     """
     Test that Firecracker swagger specification is valid.
     """
-    swagger_spec = Path("../src/firecracker/swagger/firecracker.yaml")
+    swagger_spec = Path("../src/firecracker/openapi/firecracker.yaml")
     validate_swagger(swagger_spec)

tools/bump-version.sh

@@ -32,7 +32,7 @@ prev_ver=$(get_swagger_version)
 say "Updating from $prev_ver to $version ..."
 # Update version in files.
 files_to_change=(
-    "$FC_ROOT_DIR/src/firecracker/swagger/firecracker.yaml"
+    "$FC_ROOT_DIR/src/firecracker/openapi/firecracker.yaml"
     "$FC_ROOT_DIR/src/firecracker/Cargo.toml"
     "$FC_ROOT_DIR/src/jailer/Cargo.toml"
     "$FC_ROOT_DIR/src/rebase-snap/Cargo.toml"

tools/functions

@@ -94,7 +94,7 @@ get_user_confirmation() {
 
 # Get version from the swagger file
 function get_swagger_version {
-    local file=${1:-"$FC_ROOT_DIR/src/firecracker/swagger/firecracker.yaml"}
+    local file=${1:-"$FC_ROOT_DIR/src/firecracker/openapi/firecracker.yaml"}
     grep -oP 'version: \K.*' "$file"
 }
 

tools/release.sh

@@ -171,8 +171,8 @@ done
 cp -v "resources/seccomp/$CARGO_TARGET.json" "$RELEASE_DIR/seccomp-filter-$SUFFIX.json"
 # Copy over arch independent assets
 cp -v -t "$RELEASE_DIR" LICENSE NOTICE THIRD-PARTY
-check_swagger_artifact src/firecracker/swagger/firecracker.yaml "$VERSION"
-cp -v src/firecracker/swagger/firecracker.yaml "$RELEASE_DIR/firecracker_spec-$VERSION.yaml"
+check_swagger_artifact src/firecracker/openapi/firecracker.yaml "$VERSION"
+cp -v src/firecracker/openapi/firecracker.yaml "$RELEASE_DIR/firecracker_spec-$VERSION.yaml"
 
 CPU_TEMPLATES=(c3 t2 t2s t2cl t2a v1n1)
 for template in "${CPU_TEMPLATES[@]}"; do