TypeSpec — Typescript based OpenAPI file generation

How many times, have we thought that should we be writing API spec first or directly jump in the code & let it generate the API spec file on demand, that can be used by the clients to see how our API behaves. The second approach seems to be the right one, as a coder we always love to jump on the keyboard with our heads down and try to produce as fast as we can “A WORKING CODE”. However, it seems almost most of the times, if we sit and jot all our thoughts on paper we are doing a great help to our code and how we want to organize it. Isn’t it simpler if we have a paper briefing down how we are going to broke our code in folders/files/functions/utilities etc.

Writing a API SPEC (or i should say OPENAPI2/3 spec) is always a great way to collect all the various edges in which our API can behave. Writing a SPEC file is always a time consuming task with all those YAML Declarations (or json if you prefer that) and the cryptic relative connections between various components. Thankfully, Microsoft has released a NODEJS based library that helps us to write a small TYPESPEC file and it will automatically generate our OPEN API Spec file that can be distributed to the consumers. The syntax is appears to be developed on top of TypeScript and very similar to TS.

This will be a series of posts about TYPESPEC (if the audience find it useful,) however in this post I am just going to illustrate, how I have started with this and how useful it is. In less then half an hour I am able to write a typespec file (or i should say Open API)

TYPESCRIPT PlayGround:
https://typespec.io/playground

If the installation process seems complex, no issues, just head over to typescript playground and see it action on the browser. One the left hand side is our TSP code and on the right is the autogenerated OpenAPI yaml (both editor and swagger).
Paste the below following contents in the left hand side of the playground (this is our main.tsp file)

import "@typespec/http";
import "@typespec/rest";
import "@typespec/openapi3";
import "@typespec/versioning";using TypeSpec.Http; 
using TypeSpec.Rest; 
@service({
    title: "Employee Service"
})
@server("https://{SERVER}", "EMPLOYE EAST SERVER ENDPINT", { SERVER?:string = "eastus.com/api/v1"})
@route("/employees")
@tag("Employee Service")
namespace EmployeeService{
@get op listEmployees(@query size?: int8 , @query page:int8,
@query({format: "csv"}) csv?: string[], ) : Employee[]; 
@get op getEmployee(@path empId : int32) : Employee; 
@post op createEmployee(@body emp : Employee, @header xApiKey : string) : Employee;
@get 
@route("/status")
op getStatus() : string; 
model Employee {
    @maxLength(50)
    @minLength(10)
    name : string; 
    fName : string; 
    lName : string; 
    age : int8; 
    sex : "F" | "M"; 
}
}