3 ms·

Or use jsonrpc and your documentation is ie typescript definition file, a list of function signatures.

• verdverm 3y ago
  most things are not written in typescript OpenAPI, being JSON or Yaml, is portable
  • mirekrusin 3y ago
    JsonRPC is also portable. Whole spec fits single page.
    • verdverm 3y ago
      the JsonRPC comes from the typescript in GP, so the process of schema generation from types is not portable to other languages...
      • mirekrusin 3y ago
        Typescript is mentioned as an example of function signature format. As it needs to describe only valid json values, the whole language needs to operate on 6 underlying data types only - it's really not that complicated to come up with minimal readable format that's easy to parse. It doesn't matter much if it reassembles ts, flow, ocaml or haskell - the point is it can fit into single screen, serve as documentation and be parseable for verification/codegen etc.
        • verdverm 3y ago
          Let's step back, and remember you posed JsonRPC as an alternative to OpenAPI or something like that? There is a whole lot more to express than... > 6 underlying data types only ... when automating REST documentation from some underlying source of truth It seems this one-page spec is woefully insufficient to express the concepts that OpenAPI can. Hence why no one here thinks this is a viable alternative
          • mirekrusin 3y ago
            OpenAPI is cluttered with protocol specifics that are irrelevant to something that is native to your host language (function signatures). Think of it as header file for api that is highly constrained (functions, notifications and json data types only - no classes, instances, polymorphism, no way to encode callbacks or returning functions etc. just basic algebra on json types - type aliases and unions). Imagine api like this: // @endpoint wss://localhost:3000/api/v1 notification heartbeat = { timestamp: number } type User = { id: string, email: Email type: "normal" | "admin" } type AuthError = { message: string, code: -123 } type NotLoggedInError = { message: string, code: -124 } // Logs you in. // // @throws AuthError login(username: string, password): User // Adds two numbers. // @throws NotLoggedInError add(x: number, y: number): number // Logs you out. // @throws NotLoggedInError logout(): null It's terse, straight forward and maps to your host programming language naturally.
• mdaniel 3y ago
  I don't think that's even remotely true, based on https://www.jsonrpc.org/specification#examples https://www.jsonrpc.org/specification#examples
  • mirekrusin 3y ago
    Just like author simplifies HTTP communication, you can simplify: --> {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1} <-- {"jsonrpc": "2.0", "result": 19, "id": 1} ...example to: subtract(42, 23) -> 19
    • verdverm 3y ago
      How do you express the schema for the jsonrpc endpoints being served? What are valid methods and parameters?
      • mirekrusin 3y ago
        Subset of flow would work the best.
        • verdverm 3y ago
          but that's not widely implemented, while OpenAPI is there are reasons people left flow, why do you think it is a candidate for best? Simply claiming so does nothing to further anyone's understanding
          • mirekrusin 3y ago
            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.