Develop OpenAPI Export for API Definition

[jdegoes]

In order to make it easy to standup REST APIs atop workers, Golem has a concept of "API Definition", which consists of a number of routes, with binding types, and implemented by the Worker Gateway (worker bridge + worker services).

Currently, two binding types are supported in the Worker Gateway:

• Default. In this case, each binding is given by a snippet of Rib, which calls into a function that has been exported from the worker handling the request. The Rib script serves to massage the JSON input into whatever form is required by the function being invoked; and then again, to massage the output of the function into whatever from is required by the JSON response.
• File Server. In this case, the endpoint serves static files, which are determined by a Rib script.

Rib is a fully type-inferred language, and type information is available as metadata on existing REST APIs. This type information describes the type of input and output as a type in WASM's Component Model--see WIT for a sense of what these types can represent.

The Rib interpreter has a canonical mapping of values to Component Model types. It's deterministic and predictable and somewhat documented.

For all these reasons, it is possible to know exactly the input JSON and output JSON of every endpoint.

This ticket is to add a new REST API that can export an API Definition into a valid OpenAPI Specification, preserving the request and response types. Separately, the OpenAPI Specification needs to correctly represent security and CORs, which are features of the Worker Gateway. Any client library generated from the OpenAPI Specification needs to be able to work correctly with the real REST API.

/v1/api/definitions/{id}/version/{version}/export

Moreover, the ticket also calls for use of the OpenAPI Spec to generate a Swagger UI; and for a new binding type in the Worker Gateway, which can trigger the Worker Gateway to serve the Swagger UI at the specified endpoint.

Together, all these features will provide very good support for consuming REST APIs built with the Worker Gateway.

To close out this ticket, the following tasks must be completed:

• Full and lossless conversion of any API Definition into a valid OpenAPI Specification.
• Tests at the unit and integration level which demonstrate the correctness of pieces and the whole.
• System tests that generate client libraries from the OpenAPI Spec, and interact to verify the client library works.
• Manual testing for complex scenarios.
• Full documentation, submitted separately in a PR to the docs repository in the golemcloud organization.
• A new binding type for routes called "Swagger UI", which will use serve Swagger UI at the specified route, which are generated during API Definition update (if necessary) and stored for subsequent serving of the endpoint.

[jdegoes]

/bounty $10000

[algora-pbc]

💎 $10,000 bounty • Golem Cloud

Steps to solve:

1. Start working: Comment /attempt #1178 with your implementation plan
2. Submit work: Create a pull request including /claim #1178 in the PR body to claim the bounty
3. Receive payment: 100% of the bounty is received 2-5 days post-reward. Make sure you are eligible for payouts

Thank you for contributing to golemcloud/golem!

Add a bounty • Share on socials

Attempt	Started (GMT+0)	Solution
🔴 @Myestery	Dec 13, 2024, 5:44:18 AM	WIP
🟢 @debaa98	Dec 13, 2024, 6:05:08 AM	WIP
🟢 @uurl	Dec 13, 2024, 7:31:41 PM	#1203
🟢 @HollandDM	Dec 14, 2024, 7:48:06 AM	WIP
🟢 @sreehariX	Dec 17, 2024, 11:22:02 AM	WIP
🟢 @zelosleone	Dec 18, 2024, 9:36:45 AM	#1202

[Myestery]

/attempt #1178
I can send a working implementation of this within the next week

Algora profile	Completed bounties	Tech	Active attempts	Options
@Myestery	2 bounties from 2 projects	MDX, TypeScript, JavaScript & more		Cancel attempt

[debaa98]

/attempt #1178

Options

• Cancel my attempt

[uurl]

/attempt #1178

Options

• Cancel my attempt

[HollandDM]

/attempt #1178

Options

• Cancel my attempt

[sreehariX]

/attempt #1178

Options

• Cancel my attempt

[zelosleone]

/attempt #1178

Options

• Cancel my attempt

[algora-pbc]

💡 @zelosleone submitted a pull request that claims the bounty. You can visit your bounty board to reward.

[algora-pbc]

💡 @uurl submitted a pull request that claims the bounty. You can visit your bounty board to reward.