[PMM-630]: Update TypeSpec Guide #93
Conversation
|
🔗 Preview your changes |
philsturgeon
force-pushed
the
guide/typespec
branch
from
6d74bc6 to
9985983
Compare
|
@ndimares ready for January. |
baywet
left a comment
baywet
left a comment
There was a problem hiding this comment.
This is great, I gave it a high level review. Beyond the ad-hoc comments, it might be worth expanding two aspects:
- Why would anyone choose to get SDKs generated from Speakeasy vs TypeSpec since this is a new possibility from adopting TypeSpec?
- An important benefit from using TypeSpec is to enable the use of linting rules directly in the contract tooling (no 3rd party required). That improves the API consistency and quality, which in turns improves the quality of SDKs (however they end up being generated).
| @route("/stores") | ||
| interface Stores { | ||
| list(@query filter: string): Store[]; | ||
| read(@path id: Store): Store; |
There was a problem hiding this comment.
wouldn't you want the id to be a string instead?
| ```typescript filename="main.tsp" | ||
| @route("/users") | ||
| interface Users { | ||
| op listUsers(): User[]; // Defaults to GET /users |
There was a problem hiding this comment.
maybe it'd be worth using the shorthands (read, list, etc...) instead of op listUsers? For consistency with the new store example.
| Here's an example of a complete TypeSpec file for a Book Store API: | ||
| Here's an example of a complete TypeSpec file for a Train Travel API: | ||
| ```typescript |
There was a problem hiding this comment.
I've noticed you're using typescript as the language for the back-ticks. GitHub support TypeSpec, I'm not sure what rendering engine you're using, but it might be worth trying converting those for a better experience.
| ``` | ||
|
|
||
| The `tsp compile` command creates a new directory called `tsp-output`, then the `@typespec/openapi3` emitter creates the directories `@typespec/openapi3` within. If we were to use other emitters, such as protobuf, we would see `@typespec/protobuf` directories instead. | ||
| This will configure TypeSpec to emit OpenAPI 3.2 specifically, which is a newer version of OpenAPI supported by both TypeSpec and Speakeasy. For an older version, change the `openapi-versions` value to `3.1.0`. |
There was a problem hiding this comment.
Maybe rephrase this to "add" the version. So customers get both the compatible one for their older tooling, and the latest and greatest?
| While TypeSpec is a powerful tool for generating OpenAPI documents, there are some limitations to be aware of when using it with Speakeasy. | ||
|
|
||
| ### 1. Limited Support for Model and Operation Examples | ||
| ### 1. No Extensions at the Namespace Level |
There was a problem hiding this comment.
It'd be worth creating an issue about that. If there's an extension on the document, it should be convertible back and forth from TypeSpec. Argument being: it should be as symetrical as possible.
There was a problem hiding this comment.
Also, this doesn't seem to be correct anymore?
2 participants
TypeSpec has matured a lot since this was written for 0.58, it's on 1.7.0 now and supports OpenAPI v3.2, so lets update all our examples and talk about the future.
Please merge sample code: speakeasy-api/examples#40
Please delete this old repo: https://github.com/speakeasy-api/typespec-openapi-example