Comment by rendall | Hacker News Reader

Comment by rendall | Hacker News Reader

There is definitely need for better tools and discoverability for server-clent APIs. Protobufs seems like an odd take but I'm looking forward to their subsequent articles

The best in class right now is Open API 3, which offers a way to describe endpoints, verbs and expected responses with a JSON schema. And even so, working with it feels primitive compared to, for instance, front end focused tools with bundling, type checking, package management and so forth.

With Open API 3 / Swagger, you hand write a YAML or JSON file or fill out a form and have it done for you, but there is no code completion nevermind AST analysis. And now you have a schema, but there is no automatic link between that schema and the backend code, nor error typing, nor validation. The code generation options that are available are clunky and not customizable. If you change the code, you just have to go over the schema by hand again and make adjustments. Unit tests help of course, but you build it yourself

As for server responses, there aren't really coalescing best practices. There are many possibilities for incoming and outgoing headers, but no language or library to ensure getting them right, the way that TypeScript works for instance

I really feel like this is greenfield territory, but that's strange, since it's pretty critical

It definitely is greenfield territory

At work we have a java backend and a typescript frontend. I wrote some java code that traverses the api endpoints and generates typescript definitions for them. It's completely bespoke of course. I also had to write a small java compiler plugin to record the type parameters for method return values on our api endpoints.

In .NET Core there is a nuget package you can add that generates the open api docs based on your controllers. It's a good start, though to make it fully accurate you have to add the right attributes to each endpoint. It works pretty well.

What I find really irksome about the .NET openapi tooling is the client generators use RestSharp under the hood which doesn't support HttpClient. There's no way you shouldn't be using HttpClient in 2020. So companies leveraging openapi to generate their SDKs are generating sub-par code.

What's the problem with RestSharp?

Used it a while ago and it was pretty easy to use.

It doesn't use HttpClient under the hood. So, it can't make use of DelegatingHandlers. Polly is build on DelegatingHandlers. They're incredibly useful.

RestSharp is old. It's from a bygone era when making Http requests in .NET looked very different.

You'll find Refit or Flurl are also easy to use but are a significant upgrade due to being able to use HttpClient.

You don't have to hand-write your openapi.yaml. we are using quarkus, and by annotating the endpoints you get a generated openapi.yaml.

We then use this in a typescript generator to generate client code.

I understand more than a few do this and love this. To me the schema & design should test the implementation. If you generate the schema based on the implementation, your schema is basically implicit.

I dont think by doing it this way you really get the benefit of the premise of this article. You get some other benefits, like API documenation and perhaps client code generation and that's perfectly ok if that's all you need.

However, if you believe in the idea of schema-driven, design-first api development, don't do this.

I think the parent comment doesn't mean that the schema is generated from the implementation, but that there are annotations colocated with the code that provide metadata to generate the schema.

This is what I do. I have typescript functions that generate openapi responses.

I do generate the schémas from sequelize models, blending in descriptions and enums where appropriate.

https://southpole.stoplight.io/docs/calculate/docs/CSV%20imp...

We first write the OpenAPI spec in collaboration with non-developer stakeholders (product managers or whatever).

Then we write the code to implement the spec. (We tried using code generators for this step, but quickly dropped them. If your language and web frameworks are sufficiently concise, adapting the generated code to your needs is likely to be more work than just writing from scratch.)

Then we enable an automatic tool to automatically generate an OpenAPI spec from the code. We can then compare it to the original spec to quickly see if we missed something. It's not an automated diff, but it still saves a _ton_ of time.

Finally, we use code generators for the client code. Those actually work pretty well, unlike server-side code generators, probably because there's little room for customisation in making HTTP requests.

Agreed, I'm shocked there aren't any frameworks with a focus on integration between the database ORM/schema, authn/authz, I/O validation, the data model in the client bindings, etc. None of this stuff is new or controversial ever since OpenAPI 3 came out, but I'm not aware of anyone who has even tried.

I'll ding one more thing about Open API 3.

While it is an open spec, the spec maintainer, Swagger, definitely keeps its fingerprint on it for business reasons. Among other issues, their validation tools in particular require a sign-up. Postman also has an Open API 3 schema builder, but also requires a sign up. There is no technical reason for this, and you have to trust Swagger or Postman to be responsible with your API schema. I believe this front-and-center branding of the spec itself makes it not as appealing or dynamic as it otherwise would be

edit ApiBldr seems ok: https://apibldr.com/

edit 2 AsyncAPI seems interesting: https://www.asyncapi.com/

You may want to give https://apitools.dev/swagger-parser/online/ a try to validate OpenAPI (fka Swagger) files.

You can do it online without a sign up or use the API or CLI according to your preference.

Reply on news.ycombinator.com