Keeping requests in step with the spec
apigenie test sync (since 0.13.0) checks the requests of .http files that # @operation binds to
an OpenAPI or Swagger 2.0 document against it. It reports which requests are in sync, which drifted,
which are bound to an operation that is gone, and which operations have no request yet. With
--write, it merges the document into the requests and keeps what you wrote: your values,
{{variables}}, scripts, assertions and comments stay, and only what the document changed is taken.
apigenie test sync --spec SPEC [--write] [--base FILE | --base-rev REV] FILES...
The options of sync go after sync: apigenie test --timeout 5 sync ... is refused, since
--timeout before sync is an option of a test run.
| Option | Meaning |
|---|---|
FILES |
.http and .rest files, or directories to search for them; at least one, required |
--spec SPEC |
The OpenAPI 3.x or Swagger 2.0 document the requests are bound to; required |
--write |
Merge the document into the request files, and keep it in --base as the base of the next merge. Off by default: the files are only checked |
--base FILE |
Where the merge base is kept. Default: http-sync-base.json in the first directory of FILES, else next to the first file |
--base-rev REV |
Take the merge base from a Git revision of --spec (a commit, a branch, a tag) instead of --base; nothing is kept |
--json |
Print the status of the run as JSON, with the report in its output |
An example
The requests in requests/pets.http were written for the first version of openapi.yaml, and
requests/http-sync-base.json holds that version, kept there by the --write that last brought
them in step:
### list
# @operation listPets
GET {{host}}/pets?limit=5&sort=name&debug=1
### create
# @operation createPet
POST {{host}}/pets
Content-Type: application/json
{"name": "{{petName}}", "age": "4"}
### ping
GET {{host}}/ping
The second version of openapi.yaml drops the sort query parameter, adds a required tenant
one (example: acme), turns age into an integer (example: 3) and adds DELETE /pets/{petId} (deletePet). debug was in neither version: you added it.
apigenie test sync --spec openapi.yaml requests
requests/pets.http:3: drifted: list: the query parameter sort is no longer in the spec (--write merges it)
requests/pets.http:3: drifted: list: the query parameter debug is not in the spec (merge it by hand)
requests/pets.http:3: drifted: list: the query parameter tenant is required by the spec and missing (--write merges it)
requests/pets.http:10: drifted: create: /age of the body is integer in the spec, not a string (--write merges it)
requests/pets.http:13: local only: ping (no # @operation)
no request: deletePet (DELETE /pets/{petId})
0 in sync, 2 drifted, 0 bound to a gone operation, 1 local only; 1 operations without a request
Merge base: requests/http-sync-base.json
Each line about a request names the file, the line it is about (the request line, a header, the
body or the # @operation), the request’s status, its # @name (else its ### title, else its
method and URL) and the difference.
The report
Each HTTP request of the files is one of:
- in sync with its operation;
- drifted, with a line for each difference;
- bound to an operation that is gone from the document, with the operation its URL matches, if one does;
- local only: it has no
# @operation, or has# @operation off.
The operations with an operationId that no request is bound to are listed after them; one that
a rename --write merges would bind a request to counts as bound. WS, MQTT, KAFKA, AMQP,
GRAPHQL and GRPC regions are left out.
What is compared:
- the method;
- the path, by its last segments against the operation’s path template: a server’s base path
or a
{{host}}before it doesn’t matter, and a{{variable}}matches any parameter; - the query parameters: one the document doesn’t declare, and a required one that is missing;
- the headers: a required header parameter that is missing and, with a merge base, a header that the base declared as a parameter and the document no longer does. Other headers are yours;
- whether the operation takes a request body, and whether it requires one;
- a JSON body, property by property: properties the schema doesn’t declare, values of another
type, enum values it doesn’t allow, and required properties that are missing. A schema with
propertiesand noadditionalProperties(oradditionalProperties: false) declares only those;additionalProperties: trueor a schema allows any other.allOfis merged. ForoneOfandanyOf, the body is checked against the branch that declares most of its properties, and a matchingconstorenum(a discriminator) counts more.
The merge base
A parameter or a property that the document doesn’t declare is either yours (added on purpose,
or a value of another type to test an error) or one the document dropped. Only the previous
version of the document tells them apart, so the merge takes it as its base. --write keeps the
document, bundled as JSON, in http-sync-base.json. Commit that file with the request files, so
that every machine and CI merge from the same base. The base belongs to the files as a whole:
sync the same files each time.
--base-rev v1.4.0 takes the base from Git instead: the --spec file as it was at that revision.
The references of that file to other local files are read from the working tree, not from the
revision.
Without a base, as on the first run, nothing you wrote is removed or replaced: what the document
doesn’t declare is reported as merge it by hand and stays. --write then only adds what the
document requires (required query and header parameters, required body properties, a required
body) and keeps the document as the base of the next merge.
What --write merges
The drift reported as --write merges it:
- the method and the path of an operation the document moved (with a base), keeping the values of the path parameters by name and the part of the path before the operation’s;
- query parameters and header parameters the document dropped (with a base) are removed;
required ones it added are added, with the values
--generatemakes; - a JSON body keeps your values and
{{variables}}. With a base, properties the document no longer declares are removed, and a value whose type the document changed, or an enum value it dropped, is replaced. Required properties are added and, with a base, so are the properties the document added (from the schema’s examples, else generated); - a body the operation now requires is added, and one it no longer takes (with a base) is removed;
- a request bound to an operation that the base had at the same method and path, under another
operationId, gets the new one in its# @operation, unless another request is already bound to it.
What is reported as merge it by hand stays as it is:
- without a base, everything but a missing required value;
- with a base, what the base didn’t declare either: a parameter (a name that an object parameter only took as any property counts as undeclared), a property, a value of another type than the base’s, an enum value, a method or a path;
- an operation that is gone, or one renamed to an
operationIdanother request is already bound to; - a body the operation no longer takes in a
< file, or of a media type the document doesn’t take; - a JSON body that doesn’t parse or repeats a property;
- a value the document requires, adds or changed that can’t be made from it (no example, and no schema to generate one from, or an object with no properties to fill in).
Only the lines that change are rewritten: the request line with its ? and & lines, a header,
the body. Line ends and the rest of the file stay. A JSON body that changes is written compact,
without spaces, when it was on one line, else indented like it was.
With --write, each merged difference is printed as merged: instead of drifted:, each
rewritten file as FILE: written, and the counts are those before the merge. The last lines say
where the merge base came from (Merge base: FILE, Merge base: git REV:PATH, or No merge base (FILE not found): ...) and, when the base file changed, that the document was kept in it:
requests/pets.http:3: merged: list: the query parameter sort is no longer in the spec
requests/pets.http:3: drifted: list: the query parameter debug is not in the spec (merge it by hand)
requests/pets.http:3: merged: list: the query parameter tenant is required by the spec and missing
requests/pets.http:10: merged: create: /age of the body is integer in the spec, not a string
requests/pets.http:13: local only: ping (no # @operation)
requests/pets.http: written
no request: deletePet (DELETE /pets/{petId})
0 in sync, 2 drifted, 0 bound to a gone operation, 1 local only; 1 operations without a request
Merge base: requests/http-sync-base.json
Kept the spec in requests/http-sync-base.json as the base of the next merge; commit it with the requests
The requests are then:
### list
# @operation listPets
GET {{host}}/pets?limit=5&debug=1&tenant=acme
### create
# @operation createPet
POST {{host}}/pets
Content-Type: application/json
{"name":"{{petName}}","age":3}
### ping
GET {{host}}/ping
When a request file can’t be read or written, the other files are still checked and written, but the merge base is not updated.
Exit status
| Code | Meaning |
|---|---|
| 0 | Every request bound to an operation is in sync; with --write, all the drift was merged |
| 1 | A request drifted or is bound to an operation that is gone; with --write, one has drift to merge by hand |
| 2 | No --spec or no FILES, a path of FILES that doesn’t exist, --spec or the merge base can’t be read, --base-rev can’t be read from Git, --base with --base-rev, an option of the test run before sync, a request file that can’t be read or written, the merge base that can’t be written, or an unexpected error |
Not yet
- New enum values are not added as disabled entries, since
.httphas no disabled values. - Bodies other than JSON, and
< filebodies, are only checked for being required or gone. - Cookies and the values of URL parameters are not compared.