Azure / Azure/azure-rest-api-specs

[TypeSpecValidation] Ensure all swagger files can be regenerated from typespec

Open
#30,916 0 comments 0 reactions 1 assignee Claimed by @mikeharder View on GitHub
Dominant language
TypeSpec
Stars
3.1k
Forks
5.9k
Avg merge
2d 22h
Merged PRs (30d)
444

Description

The check tries to ensure the TSP and swagger are in sync via this algorithm:

1. Run `tsp compile .` (and optionally `tsp compile client.tsp`)
2. Run `git diff`
3. If any files have been added, modified, or deleted: FAIL

This catches most ways that TSP and swagger can be out-of-sync, but it misses an important one. If a swagger file (containing `x-typespec-generated`) is manually added to the output folder, we **don't** verify that the file can be re-generated by running `tsp compile`. We only verify that running `tsp compile` doesn't **change** any output files.

One way to fix this, is to **delete** any files we think should be generated by a given TypeSpec folder, before running `tsp compile`.

Example:

```
cognitiveservices
/AnomalyDetector
/tspconfig.yaml
azure-resource-provider-folder: "data-plane"
emitter-output-dir: "{project-root}/../"
output-file: "{azure-resource-provider-folder}/{service-name}/{version-status}/{version}/openapi.json"
/data-plane
/AnomalyDetector
/preview
/v1.1-preview.1 (handwritten)
/v1.1-preview.2 (handwritten)
/stable
/v1.0 (handwritten)
/v1.1 (generated)
```

New algorithm:

1. Parse tspconfig.yaml, extract output folder setting, replace variables. Example: "../data-plane/AnomalyDetector"
2. Under output folder, delete all JSON files contaning `x-typespec-generated`.
3. Run `tsp compile .`
4. Run `git diff`
5. If any files have been added, modified, or deleted: FAIL

This way, if a new version is manually added to the output folder, without corresponding TSP sources, it will be detected as a deleted file.

A remaining gap in this algorithm, is if a new top-level folder is added under `data-plane|resource-manager`, without corresponding TSP sources. This is a slightly different case, since each top-level folder under `data-plane|resource-manager` is considered a distinct "spec". This will be addressed in a separate issue.

Example of invalid spec currently being missed by this gap. Swagger file with version `2024-08-01-preview`:

https://github.com/Azure/azure-rest-api-specs/blob/cf170ef8e99c2ed03edf520c54effa6d5435df28/specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview/2024-08-01-preview/generated.json

But TSP sources don't contain this version:

https://github.com/Azure/azure-rest-api-specs/blob/cf170ef8e99c2ed03edf520c54effa6d5435df28/specification/cognitiveservices/OpenAI.Inference/main.tsp#L76-L78

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.