If flow adoption in js bothers you, just replace it with "subset of ts" - it'd look almost the same (it's better when it comes to things like declaring exact vs inexact object types or having cosmetic shorthand for optional type).
The bottom line is that description is terse and natural. Ie. it can be generated directly from your code and code can be generated out of it.
Instead of describing protocol (headers, status codes, http verbs, redirects, urls, params, cookies, content types etc) - you describe function signatures - the very thing that already has first class support in your programming language. An api feels like a library.
Because it uses json as serialization the data types you need to cover are very small - there are no interfaces, classes, inheritance, functions (you can't provide or return objects that define functions) - everything is pretty much composed out of type aliases and unions on 6 basic json types.
Instead of programming in yaml to describe http protocol you work with functions having json on input and output - something that is natural to your host programming language already.
Think graphql but without its nonsense restrictions on query (unions on input are fine!) or cherry picking output (calling convention that is foreign to programming languages and requires embedding dsl/dedicated query engines).
Think more like header file for remote service constraint to list of functions and notifications using json as data type.
