6 ms·

+1. It even looks very similar to TypeScript. Why not use TypeScript as a description of APIs in the first place? Get TypeScript types and even generate OpenAPI

+1. It even looks very similar to TypeScript. Why not use TypeScript as a description of APIs in the first place? Get TypeScript types and even generate OpenAPI schema on the fly to serve it at `/openapi`?

darylteo 2y ago
Exactly - this is already a solved problem. https://docs.nestjs.com/openapi/introduction https://docs.nestjs.com/openapi/introduction
- BillyTheKing 2y ago
  yes, the whole world runs on nestjs
  - darylteo 2y ago
    https://github.com/domaindrivendev/Swashbuckle.AspNetCore https://github.com/domaindrivendev/Swashbuckle.AspNetCore https://github.com/RicoSuter/NSwag https://github.com/RicoSuter/NSwag There is no need to be facetious, solutions like these exist for many platforms and ecosystems out there. I can't possibly entertain all of them. By all means, if such similar solution does not exist for your platform, then TypeSpec could indeed be a solution for you. With best regards.
    - DanielHB 2y ago
      The solutions you are talking about are called "code-first", TypeSpec is a "schema-first" solution. Both solutions have their pros and cons: Code-first: - No extra steps between code and running application - No mismatch between schema and code - Requires tooling for every language used in your stack. This tooling is usually more complex than schema-first codegen, but it is almost always built-into and core of the backend framework you are using so it tends to be better supported. - Requires teams to know each service's backend language to propose changes - Harder to build a coherent central API documentation if you have multiple services. Requires complex tooling for merging the different schemas from the different services Schema first: - Schema first means contract-first design, scales better to products with multiple separate teams using multiple languages. It is easier to learn the schema DSL than poke around backend language unknown to the developer - Any change in the contract requires changes in two places (schema and code) - API consumers can easily suggest changes to the schema that are implemented by the relevant team - Usually requires some codegen step for each backend and client languages (with the usual codegen problems). Runtime-only schema validation can be done but it is usually a bad idea to rely only on it. - Easier mocking. Clients can start implementing before backend is ready, tests can be written against mocks. There are definitely more pros and cons that I am missing, but it is a tradeoff. I would say if you have multiple backend services and supporting multiple backend languages I would definitely go for schema-first. You can work with OpenAPI in a schema-first way but as many people have pointed out over the years OpenAPI yaml files are, to be polite, not very human-friendly. TypeSpec seems to be a more sensible way to work with HTTP apis in a schema first way while keep interoperability with existing OpenAPI tooling at the cost of extra codegen step (typespec .tps -> openapi .yaml)
- deleted 2y ago
  [deleted]
DanielHB 2y ago
Typescript is too powerful, there are a lot of typescript constructs that can't be represented in OpenAPI specs. Or that could generate massively complex OpenAPI specs that would bring your tooling performance to a crawl. A subset of typescript could work, but I imagine it would be fairly confusing to support some features here and other features there. I think they are going for a minimum common denominator approach and eventually add other targets besides OpenAPI.

darylteo 2y ago

Exactly - this is already a solved problem. https://docs.nestjs.com/openapi/introduction https://docs.nestjs.com/openapi/introduction

BillyTheKing 2y ago
yes, the whole world runs on nestjs
- darylteo 2y ago
  https://github.com/domaindrivendev/Swashbuckle.AspNetCore https://github.com/domaindrivendev/Swashbuckle.AspNetCore https://github.com/RicoSuter/NSwag https://github.com/RicoSuter/NSwag There is no need to be facetious, solutions like these exist for many platforms and ecosystems out there. I can't possibly entertain all of them. By all means, if such similar solution does not exist for your platform, then TypeSpec could indeed be a solution for you. With best regards.
  - DanielHB 2y ago
    The solutions you are talking about are called "code-first", TypeSpec is a "schema-first" solution. Both solutions have their pros and cons: Code-first: - No extra steps between code and running application - No mismatch between schema and code - Requires tooling for every language used in your stack. This tooling is usually more complex than schema-first codegen, but it is almost always built-into and core of the backend framework you are using so it tends to be better supported. - Requires teams to know each service's backend language to propose changes - Harder to build a coherent central API documentation if you have multiple services. Requires complex tooling for merging the different schemas from the different services Schema first: - Schema first means contract-first design, scales better to products with multiple separate teams using multiple languages. It is easier to learn the schema DSL than poke around backend language unknown to the developer - Any change in the contract requires changes in two places (schema and code) - API consumers can easily suggest changes to the schema that are implemented by the relevant team - Usually requires some codegen step for each backend and client languages (with the usual codegen problems). Runtime-only schema validation can be done but it is usually a bad idea to rely only on it. - Easier mocking. Clients can start implementing before backend is ready, tests can be written against mocks. There are definitely more pros and cons that I am missing, but it is a tradeoff. I would say if you have multiple backend services and supporting multiple backend languages I would definitely go for schema-first. You can work with OpenAPI in a schema-first way but as many people have pointed out over the years OpenAPI yaml files are, to be polite, not very human-friendly. TypeSpec seems to be a more sensible way to work with HTTP apis in a schema first way while keep interoperability with existing OpenAPI tooling at the cost of extra codegen step (typespec .tps -> openapi .yaml)
deleted 2y ago
[deleted]

DanielHB 2y ago

Typescript is too powerful, there are a lot of typescript constructs that can't be represented in OpenAPI specs. Or that could generate massively complex OpenAPI specs that would bring your tooling performance to a crawl. A subset of typescript could work, but I imagine it would be fairly confusing to support some features here and other features there. I think they are going for a minimum common denominator approach and eventually add other targets besides OpenAPI.