Current Best Practices for Go HTTP API Design: Code-First, Schema-First, or Protobuf? Looking for the sweet spot

Hello everyone,

I am currently evaluating the workflow for designing and developing HTTP APIs in Go for my team. I'm familiar with the three most common approaches, but each seems to have significant trade-offs. I'd love to hear how other teams are handling this effectively.

Here is my assessment of the current landscape:

Code-First (Comments -> OpenAPI): Writing Go code first and generating OpenAPI docs via comments (e.g., using swag).

My take: I strictly avoid this. API design should precede implementation (Contract-First). Furthermore, cluttering the codebase with massive comment blocks feels messy, and there is no guarantee that the comments remain in sync with the actual implementation logic.
Schema-First (OpenAPI -> Code): Writing the OpenAPI YAML manually, then implementing or generating the Go code (e.g., oapi-codegen).

My take: This is my preferred conceptual approach because the contract is the source of truth. However, maintaining large, verbose YAML files manually is painful, and ensuring the implementation strictly matches the spec can be cumbersome without strict generation tools.
Protobuf-First (Proto -> gRPC Gateway): Defining APIs in Protobuf and generating the HTTP gateway.

My take: This offers the best consistency between docs and code. However, for a pure HTTP/REST API, it feels like a mismatch. Certain HTTP-specific features (File Uploads, SSE, Websockets, precise JSON control) often require messy workarounds or bypassing the gRPC logic entirely.

The Dilemma: I recently looked into TypeSpec (formerly Cadl) as a way to simplify the "Schema-First" approach (TypeSpec -> OpenAPI -> Go). While it looks cleaner, I am hesitant to introduce "yet another language/DSL" to the team's tech stack just for API definitions.

My Question: Is there a better workflow I'm missing?

How do you balance the rigor of Schema-First with developer experience?

Are there tools that bridge the gap without introducing new DSLs?

Is anyone successfully using frameworks like Huma to keep the "Code-First" experience while maintaining strict contract guarantees?

Thanks for your insights!

submitted by /u/Successful_Plant2759
[link] [comments]