Azure / Azure/azure-rest-api-specs
[TypeSpecValidation] Ensure all swagger files can be regenerated from typespec
- 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
Assessment
This issue has not been assessed yet.