TypeSpec vs OpenAPI

Very clever: Using TypeScript inspired language  for describing APIs. From Microsoft.

 typespec.io

Describe your data up front and generate schemas, API specifications, client / server code, docs, and more.

API-First for developers

With TypeSpec, remove the handwritten files that slow you down,
and generate standards-compliant API schemas in seconds.

import "@typespec/http";

using TypeSpec.Http;

model Store {

name: string;

address: Address;

}

model Address {

street: string;

city: string;

}

@route("/stores")

interface Stores {

list(@query filter: string): Store[];

read(@path id: Store): Store;

}

---

openapi: 3.0.0

info:

title: (title)

version: 0.0.0

tags: []

paths:

/stores:

get:

operationId: Stores_list

parameters:

- name: filter

in: query

required: true

schema:

type: string

responses:

'200':

description: The request has succeeded.

content:

application/json:

schema:

type: array

items:

$ref: '#/components/schemas/Store'

/stores/{id}:

get:

operationId: Stores_read

parameters:

- name: id

in: path

required: true

schema:

$ref: '#/components/schemas/Store'

responses:

'200':

description: The request has succeeded.

content:

application/json:

schema:

$ref: '#/components/schemas/Store'

components:

schemas:

Address:

type: object

required:

- street

- city

properties:

street:

type: string

city:

type: string

Store:

type: object

required:

- name

- address

properties:

name:

type: string

address:

$ref: '#/components/schemas/Address'