SDK: Expose OpenAPI spec as a public endpoint

skorfmann commented 1 year ago

Feature Spec

The SDK Api resource has an OpenAPI spec. Make it easy to consume for third party services and tooling by serving it under some path. Apparently there's not really an established default path yet (see https://github.com/OAI/OpenAPI-Specification/issues/2128 and https://github.com/OAI/OpenAPI-Specification/issues/724).

Use Cases

Manually generate clients based on the OpenAPI spec
3rd party services (e.g. OpenAI plugins)

Implementation Notes

There's https://github.com/winglang/wing/issues/2024 which goes far beyond of what's being described here.

Component

SDK

Community Notes

Please vote by adding a 👍 reaction to the issue to help us prioritize.
If you are interested to work on this issue, please leave a comment.

Chriscbr commented 1 year ago

@skorfmann Would it also be useful to exposing the OpenAPI spec as a field on the resource class (see below)? Or is having it automatically served at some well-known URI preferable?

let api = new cloud.Api():

// ... configure it

api.openApiSpec; // Json value

skorfmann commented 1 year ago

@skorfmann Would it also be useful to exposing the OpenAPI spec as a field on the resource class (see below)? Or is having it automatically served at some well-known URI preferable?
let api = new cloud.Api():

// ... configure it

api.openApiSpec; // Json value

This would be good start. That way, one could at least write it to a file and generate a client based on it.

The additional step to serve it under some path would still be very nice. Perhaps not even automatically, but by explicitly defining it. Something like

api.publishOpenApiSpec("my/path") // defaults to something sort of well known

github-actions[bot] commented 1 year ago

Hi,

This issue hasn't seen activity in 60 days. Therefore, we are marking this issue as stale for now. It will be closed after 7 days. Feel free to re-open this issue when there's an update or relevant information to be added. Thanks!

github-actions[bot] commented 5 months ago

Hi,

This issue hasn't seen activity in 90 days. Therefore, we are marking this issue as stale for now. It will be closed after 7 days. Feel free to re-open this issue when there's an update or relevant information to be added. Thanks!

Chriscbr commented 4 months ago

Note: If we expose openApiSpec as a preflight Json property, there could be some limitations because the value will not always be the latest one (leading to surprising bugs)

let api = new cloud.Api():

api.get("/spec", inflight () => {
  return {
    status: 200,
    body: Json.stringify(api.openApiSpec) // <-- "/hello" could be missing
  };
});

api.get("/hello", ...);

Some solutions to this could be making openApiSpec a token value, or making it an inflight-only field

github-actions[bot] commented 1 month ago

Hi,

This issue hasn't seen activity in 90 days. Therefore, we are marking this issue as stale for now. It will be closed after 7 days. Feel free to re-open this issue when there's an update or relevant information to be added. Thanks!

winglang / wing