zlacker

I run an API SaaS and this looks great. I've wanted to add more SDKs to my lineup, but it's a big commitment for a single person to maintain. Right now, I have a minimal Go SDK to test the waters and definitively see how much effort it takes. One hurdle I have with services like Stainless (which looks great!) is that I don't know where to start to actually codegen an OpenAPI spec from a Ruby/Rails API. Writing and maintaining the spec by hand sounds like a nightmare for any decent sized API, but I guess it's not worse than maintaining multiple SDKs (or even one). How did Stripe handle this?

>>ezekg+(OP)
From experience I can tell you that you just need to do it manually. And keep maintaing the spec manually. That keeps you aware of it. It is your contract with the outside world. You don't want tools to automatically update it everytime you push. On the contrary, you want tools to slap you hard every time you push and you forgot to update the spec. Now you're going to think hard why did you change the spec and if you maybe need to bump to /api/v2/*

As far as generating the first spec from an existing API I think there was shown here on HN a while ago a tool that can generate the spec from you just "browsing" the API with developer tools or something. Maybe even from a HAR file IIRC.

>>ezekg+(OP)
> I don't know where to start to actually codegen an OpenAPI spec from a Ruby/Rails API… How did Stripe handle this?

Stripe built their own Ruby DSL for exactly this, and it worked great. It looked something like this:

    class CreateCustomerMethod < AbstractAPIMethod
      endpoint "post /v1/customers"

      returns CustomerAPIResource
      
      required :name, String, description: "The name of the customer."
      optional :description, String, description: "Additional information about the customer."

      def execute
        # …
      end
    end

Unfortunately, I don't know of an open-source equivalent for Ruby; FastAPI in Python is the closest I know of in any language. At Stainless, we're building a TypeScript version of this, but it's still deep in dogfooding.

Most people just end up maintaining by hand and using a tool like Optic or Akita to check that it's not wildly out-of-date.