Defining the Goal
After this round of adjustments, the main goal remains unchanged, but I’ve been able to strike some massive chunks off my list. The current definition of Spec CLI now looks like this:
The Revised Scope
- Server Stubs & Client Library: Here, the results from
ogenare used directly. - Mock Server: The mock provides a testable representation of the API. It can be externally controlled for complex scenarios while remaining fully conformant to the specification.
- CLI Client: A lightweight CLI enables direct interactions—both at the command line level and through declarative requests (similar to the JetBrains HTTP Client). Ideal for quick development tests or automated checks in CI/CD.
- Payload Structs: Here too,
ogendelivers excellent results. Currently, I see no reason to deviate from the generated types. - Intermediate Format: The originally planned JSON-IR is now obsolete. TypeSpec serves as a clean foundation for OpenAPI specs, which in turn form the basis for all generation.
Code Quality and Reproducibility
The generated code should feel hand-crafted: clean, idiomatic, and free from unnecessary abstractions or external dependencies. Generation must be fully reproducible, ideally with traceable versioning—for example, through comment headers containing the Spec CLI version and the spec hash.
While the initial focus was much more strongly on TypeSpec, it is now my preferred environment for writing specs. For Spec CLI itself, however, only the OpenAPI spec is the critical dependency—which should significantly increase the tool’s acceptance.
Reducing dependencies to the lowest common denominator (OpenAPI) is a smart move for interoperability. The fact that the generated code gets by without runtime dependencies is a crucial quality feature for Go libraries. The idea of including spec hashes in the headers will massively simplify debugging when dealing with inconsistent stubs.