Generate client with response

README.md

@@ -23,6 +23,7 @@ on the real value-add for your organization.
 
 ### Client Generation
 - **HTTP client generation** - Generate type-safe HTTP clients with customizable timeout and request editors
+- **Envelope `WithResponse` clients** - Opt-in `<Op>WithResponse` siblings that return a typed envelope with per-status bodies, typed headers, and the raw `*http.Response` - useful for operations that legitimately return multiple 2xx statuses or need typed access to response headers
 - **Custom client types** - Wrap generated clients with your own types for additional functionality
 - **Error mapping** - Map response types to implement the `error` interface automatically
 

configuration-schema.json

@@ -100,7 +100,11 @@
       "properties": {
         "client": {
           "type": "boolean",
-          "description": "Client specifies whether to generate a client. Defaults to false."
+          "description": "Generate the classic client: one method per operation returning the picked 2xx body directly (e.g. UploadDocument(...) (*DocumentStored, error)). Use this when callers only need the response body and the operation has a single documented success status; headers and non-picked 2xx bodies are not exposed. Combine with client-with-response when an operation has multiple 2xx statuses or callers need typed headers - both flags can be true and the generated ClientInterface will list both styles. Defaults to false."
+        },
+        "client-with-response": {
+          "type": "boolean",
+          "description": "Generate <Op>WithResponse sibling functions that return a typed envelope: one JSON<status> field per documented response, one Headers<status> typed struct per status that declares headers, plus HTTPResponse *http.Response for raw access. Use when an operation has multiple 2xx statuses with different bodies (e.g. 201 sync + 202 queued) or when callers need typed access to headers like Location or Retry-After. Additive to client: when both are true the combined ClientInterface lists both styles. Defaults to false."
         },
         "models": {
           "type": "boolean",

docs/configuration.md

@@ -140,7 +140,9 @@ output:
 #### `generate.client`
 **Type:** `boolean` | **Default:** `false`
 
-Generate HTTP client code for calling the API.
+Generate the classic HTTP client: one method per operation that returns the picked 2xx body type directly (e.g. `func (c *Client) UploadDocument(...) (*DocumentStored, error)`).
+
+Use this when callers only need the response body and the operation has a single documented success status. Headers and non-picked 2xx bodies are not exposed by this style; for those, use [`generate.client-with-response`](#generateclient-with-response) instead, or both together.
 
 ```yaml
 generate:
@@ -149,6 +151,32 @@ generate:
 
 See [examples/client/example1/cfg.yaml](https://github.com/doordash-oss/oapi-codegen-dd/blob/main/examples/client/example1/cfg.yaml){:target="_blank"} for a complete example.
 
+#### `generate.client-with-response`
+**Type:** `boolean` | **Default:** `false`
+
+Generate `<Op>WithResponse` sibling functions that return a typed envelope: one `JSON<status>` (or `Text<status>` / `HTML<status>` / etc.) field per documented response, one `Headers<status>` typed struct per status that declares headers, plus `HTTPResponse *http.Response` for raw access (undocumented headers, raw body bytes, status string, etc.).
+
+Use this when an operation has multiple 2xx statuses with different bodies (e.g. 201 sync + 202 queued), or when callers need typed access to response headers like `Location` or `Retry-After`.
+
+Additive to [`generate.client`](#generateclient). When both flags are true, the generated `ClientInterface` lists every classic method alongside its `WithResponse` sibling so a single mock or test double covers both shapes.
+
+```yaml
+generate:
+  client: true
+  client-with-response: true
+```
+
+The four valid combinations:
+
+| `client` | `client-with-response` | Output |
+|----------|------------------------|--------|
+| `false` | `false` | No client (types/server only) |
+| `true`  | `false` | Classic client only |
+| `false` | `true`  | Envelope client only |
+| `true`  | `true`  | Both styles, combined into one `ClientInterface` |
+
+See [examples/responses/multiple/client-with-response/cfg.yaml](https://github.com/doordash-oss/oapi-codegen-dd/blob/main/examples/responses/multiple/client-with-response/cfg.yaml){:target="_blank"} for envelope-only and [examples/responses/multiple/client-combined/cfg.yaml](https://github.com/doordash-oss/oapi-codegen-dd/blob/main/examples/responses/multiple/client-combined/cfg.yaml){:target="_blank"} for the combined case.
+
 #### `generate.omit-description`
 **Type:** `boolean` | **Default:** `false`
 

examples/responses/multiple/client-combined/api.yaml

@@ -0,0 +1,95 @@
+openapi: 3.0.3
+info:
+  title: Document Upload API
+  version: 1.0.0
+
+paths:
+  /documents:
+    post:
+      operationId: uploadDocument
+      summary: Upload a document
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UploadRequest'
+      responses:
+        '201':
+          description: Document stored synchronously
+          headers:
+            Location:
+              schema:
+                type: string
+                format: uri
+            X-Request-Id:
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DocumentStored'
+        '202':
+          description: Document queued for async processing
+          headers:
+            X-Request-Id:
+              schema:
+                type: string
+            Retry-After:
+              schema:
+                type: integer
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DocumentQueued'
+        '422':
+          description: Invalid document
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationError'
+        '503':
+          description: Service unavailable. Plain-text human-readable reason.
+          content:
+            text/plain:
+              schema:
+                type: string
+
+components:
+  schemas:
+    UploadRequest:
+      type: object
+      required: [filename, content]
+      properties:
+        filename:
+          type: string
+        content:
+          type: string
+          format: byte
+    DocumentStored:
+      type: object
+      required: [id, url]
+      properties:
+        id:
+          type: string
+          format: uuid
+        url:
+          type: string
+          format: uri
+    DocumentQueued:
+      type: object
+      required: [job_id, estimated_completion_seconds]
+      properties:
+        job_id:
+          type: string
+          format: uuid
+        estimated_completion_seconds:
+          type: integer
+    ValidationError:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+        message:
+          type: string

examples/responses/multiple/client-combined/cfg.yaml

@@ -0,0 +1,8 @@
+# yaml-language-server: $schema=../../../configuration-schema.json
+package: gen
+output:
+  use-single-file: false
+generate:
+  client: true
+  client-with-response: true
+  omit-description: true