Add Automated OpenAPI Specification Tooling

[NoahMaizels]

Summary

Currently, the OpenAPI specs are written manually in yaml files. This has often led to inconsistencies between what is documented in the OpenAPI specs and the actual default values of endpoint options or behavior. There exist several tools which can be used to achieve the automatic generation of OpenAPI specs based on the code itself. This guarantees that the OpenAPI values will always be consistent with the actual code. See this article for reference for one such type of tool.

It's important to note that whatever tool is chosen, it should be one that not only automatically generates the OpenAPI specs, but also enforces that the generated specs match what is actually in the code. Some tools for generating OpenAPI specs like Swaggo allow for specs to be automatically generated from in-line comments, but do not enforce that the generated specs actually match the code, so it's important not to choose a tool like Swaggo._

Motivation

This will clear up some technical debt, since the choice to manually write the OpenAPI specs by hand was never a best practice to begin with. The longer we wait to make this change, the more difficult it may become (in case the API happens to grow in some way.) This will prevent inconsistencies between the API documentation and the actual API code, preventing user frustration and increasing the reliability of the Bee documentation.

This will also in the long term save time, since the OpenAPI specs will no longer need to be coded manually by hand, since they can be directly generated from the code itself.

Implementation

It's beyond my ability.

Drawbacks

It will require some time to research the best way to set up auto-generated specs, and probably even longer to finally implement them for the entire Bee API. It may require some refactoring of the API in order to make it work with the available tools for OpenAPI specification. It's not currently clear how long it will take to identify the right tools and approach for adding auto-generated specs, nor is it clear how much refactoring it will require or how long it will ultimately take to implement.

May require switching from mux to a different package for building the server since many tools for auto-generation of OpenAPI specs which enforce that the specs match the code do not work with mux by default.

I asked ChatGPT about some options which might work directly with mux, but I'm not familiar enough with any of these to know whether these suggestions are reasonable, here's my ChatGPT query FYI

[Cafe137]

+1

It is fairly common for HTTP clients to be generated from the OpenAPI specification too.

I'd love to see this happen and start generating the HTTP layer in Bee-JS. Currently, Bee-JS has all the types and endpoints manually written. This is to avoid misleading definitions when the actual code vs. the OpenAPI specs are not in sync.

Reliable OpenAPI specs would make it much easier to create new SDKs across a wide range of programming languages.