Meanwhile, at least in theory, with a good central spec you can generate at least the docs & much of this code, or alternatively automatically validate custom implementations & real traffic to get immediate warnings if there are discrepancies.
There's a lot of power in formal specifications.
That is all dependent on tooling though. OpenAPI is far ahead in that respect, and can achieve this goal for most HTTP APIs & a huge list of languages (see https://github.com/OpenAPITools/openapi-generator) pretty effectively. AsyncAPI is much newer though, and I think the ecosystem is still quite small, but hopefully they'll get there too eventually.
That's OpenAPI / Swagger.
AsyncApi is that, but for message queues and the like.
"describing HTTP APIs using YAML" (or JSON) is OpenApi/Swagger.
AsyncAPI appears to be the "OpenApi, but for message queues" (and similar async communication mechanisms).
> Basically all you can do is generate HTML docs from YAML.
With OpenApi, you can generate interactive docs, where you can build and execute requests against a real API (not in prod, we hope)
You can generate code off OpenApi (and not just python and Java*). Anything from just DTOs to full clients. You can generate stub servers. You can inspect server code and flag up where it differs from the spec. You can test your API.
- create openapi file - write only functions
If so, it's super nice
* Auto generate mock / containers for testing
* Generate server interfaces
* Generate models that go across the wire
* Remove boiler plate to spin up an async client, sqs, kafka etc.
That being said most of the generators are from the node sides and left a bit to be desired. I also see it falling into the same issue as open api. Most places I've been dynamically generate the open api spec.
I had written a JVM async/open api gradle plugin. That generated all the above. The nice thing was that if your server didn't implement the agreed upon spec it would fail to compile. Allowing for asynchronous development, back end/mobile/front end agree on the spec and can work on the feature at the same time.
This can also be expanded into k6/gatling. Hit this endpoint, guarantee this sla and ensure everything functions as expected. By having the contract first, you can automate a majority of the down stream tasks.
I think it has a use for contract first development, and is good in conjunction with something like avro. But it serves best in a contract first flow. Where in you define a spec, if it compiles you match the spec. Most servers don't take in a spec and define routes off operation names.
Why not dynamic async api generation? A lot of the generators reflect at run time, slowing down startup, and don't provide the most human readable definitions. Also lagging behind the latest implementation, and miss potential new features.
Automatic generation of tests à la quickcheck.
Then, pydantic/fastapi does the YAML generation for me.
It wasn't really ready for that yet at the time, but I think over time AsyncAPI will be the way to go.
[0] in retrospect probably would have been better as a normal MVC app with only the chat and audio parts over ws, but... Again, not my project.
https://hexdocs.pm/exonerate/Exonerate.html
In elixir parlance checking the schemas for REST (or in the case of asyncAPI, ws) transactions will happen based on a "plug" which injects the validation into the processing pipeline.
Is there a benefit to describing APIs using YAML instead of just, y'know, prose? Seems like basically all you can do is generate HTML docs from YAML. Ok, so let me get this straight: instead of writing docs, I write YAML... --Either way I write 1 thing,--but now I can only create docs from the problem space of the known YAML schema. So it's a lossy abstraction.
Looking around I see you can now do some basic code gen of models in any language, as long as that language is python or matches the regex /java/ . But usually these messaging systems already use some data format with schemas and code gen tools like protobuff or avro! It's not just redundant, it's a collision, because something might not match up right.
Unless there's something else, it seems like something I'd advise to NOT use.