This repository provides samples for using Microsoft TypeSpec with GitHub Actions, Workflows, Pipelines, and CI/CD to accelerate adoption of TypeSpec in GitHub. TypeSpec is a tool for generating OpenAPI.json specifications from the CADL format.
- design/api-contracts: Example API TypeSpec contracts used in the workflows.
- src: Implementations (code) of APIs.
- .github/workflows: GitHub Workflow samples.
It provides a sample workflow that checks an API implementation (in this case ASP.NET core) against the API spec in the design folder. If there are any breaking changes the workflow will fail. It also stores the differences between the implementation and the design in GitHub artifacts. To check the breaking changes uses Oasdiff.
The way it retrieves the generated API implementation is by starting the API server and retrieving the swagger.json generated by Swashbuckle. Other alternatives would be to generate the OpenApi spec using Nswag either with the same approach (starting the webserver) or with a commandline util (like the AspNetCoreToOpenApi command).
It provides a sample workflow about how to compile and push the generated openapi.json spec. A useful scenario for this workflow is when we are serving static api specs in the API implementation, or when we want to trigger other utilities to generate SDKs, publish specs, etc.
Contributions are welcome! Please see our Contributing Guidelines for more information.
This project is licensed under the MIT License - see the LICENSE file for details.