q

Jamie Tanna · Jamie Tanna · commit cc80a773d871 · 2024-03-25T10:57:50.000Z
Signed-off-by: Jamie Tanna &lt;jamie.tanna@elastic.co&gt;
diff --git a/README.md b/README.md
@@ -505,42 +505,200 @@ authorization, etc. Note that middlewares are server-specific.
 
 ### Generating API clients
 
-**??**
+As well as generating the server-side boilerplate, `oapi-codegen` can also generate API clients.
 
-This produces code such as:
+For instance, given an `api.yaml`:
 
-```go
-// TODO
+```yaml
+openapi: "3.0.0"
+info:
+  version: 1.0.0
+  title: Generate models
+paths:
+  /client:
+    get:
+      operationId: getClient
+      responses:
+        200:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ClientType"
+    put:
+      operationId: updateClient
+      responses:
+        400:
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                required:
+                - code
+components:
+  schemas:
+    ClientType:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          type: string
+    # NOTE that this is not generated by default because it's not referenced. If you want it, you need to use the following YAML configuration:
+    #
+    # output-options:
+    #   skip-prune: true
+    Unreferenced:
+      type: object
+      required:
+        - id
+      properties:
+        id:
+          type: int
+```
+
+And a `cfg.yaml`:
+
+```yaml
+package: client
+output: client.gen.go
+generate:
+  models: true
+  client: true
 ```
 
-You are then able to **??**.
+And a `generate.go`:
 
 ```go
+package client
 
+//go:generate go run github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen -config cfg.yaml api.yaml
 ```
 
-### Generating API models
+This would then generate:
 
-If you're looking to only generate the models for interacting with a remote service, for instance if you need to hand-roll the API client for whatever reason, you can do this as-is.
+```go
+package client
 
-For instance, given a `generate.go`:
+// ...
 
-```go
-package onlymodels
+// ClientType defines model for ClientType.
+type ClientType struct {
+	Name string `json:"name"`
+}
 
-//go:generate go run github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen -config cfg.yaml api.yaml
+// ...
+
+// Client which conforms to the OpenAPI3 specification for this service.
+type Client struct {
+	// The endpoint of the server conforming to this interface, with scheme,
+	// https://api.deepmap.com for example. This can contain a path relative
+	// to the server, such as https://api.deepmap.com/dev-test, and all the
+	// paths in the swagger spec will be appended to the server.
+	Server string
+
+	// Doer for performing requests, typically a *http.Client with any
+	// customized settings, such as certificate chains.
+	Client HttpRequestDoer
+
+	// A list of callbacks for modifying requests which are generated before sending over
+	// the network.
+	RequestEditors []RequestEditorFn
+}
+
+// ...
+
+// The interface specification for the client above.
+type ClientInterface interface {
+	// GetClient request
+	GetClient(ctx context.Context, reqEditors ...RequestEditorFn) (*http.Response, error)
+
+	// UpdateClient request
+	UpdateClient(ctx context.Context, reqEditors ...RequestEditorFn) (*http.Response, error)
+}
+
+// ...
+
+// ClientWithResponsesInterface is the interface specification for the client with responses above.
+type ClientWithResponsesInterface interface {
+	// GetClientWithResponse request
+	GetClientWithResponse(ctx context.Context, reqEditors ...RequestEditorFn) (*GetClientResponse, error)
+
+	// UpdateClientWithResponse request
+	UpdateClientWithResponse(ctx context.Context, reqEditors ...RequestEditorFn) (*UpdateClientResponse, error)
+}
+
+type GetClientResponse struct {
+	Body         []byte
+	HTTPResponse *http.Response
+	JSON200      *ClientType
+}
+
+// ...
 ```
 
-And a `cfg.yaml`:
+With this generated client, it is then possible to construct and utilise the client, for instance:
 
-```yaml
-package: onlymodels
-output: only-models.gen.go
-generate:
-  models: true
+```go
+package client_test
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"net/http"
+
+	"github.com/deepmap/oapi-codegen/v2/examples/client"
+)
+
+func TestClient_canCall() {
+	// custom HTTP client
+	hc := http.Client{}
+
+	// with a raw http.Response
+	{
+		c, err := client.NewClient("http://localhost:1234", client.WithHTTPClient(&hc))
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		resp, err := c.GetClient(context.TODO())
+		if err != nil {
+			log.Fatal(err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			log.Fatalf("Expected HTTP 200 but received %d", resp.StatusCode)
+		}
+	}
+
+	// or to get a struct with the parsed response body
+	{
+		c, err := client.NewClientWithResponses("http://localhost:1234", client.WithHTTPClient(&hc))
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		resp, err := c.GetClientWithResponse(context.TODO())
+		if err != nil {
+			log.Fatal(err)
+		}
+		if resp.StatusCode() != http.StatusOK {
+			log.Fatalf("Expected HTTP 200 but received %d", resp.StatusCode())
+		}
+
+		fmt.Printf("resp.JSON200: %v\n", resp.JSON200)
+	}
+
+}
 ```
 
-And an `api.yaml`:
+### Generating API models
+
+If you're looking to only generate the models for interacting with a remote service, for instance if you need to hand-roll the API client for whatever reason, you can do this as-is.
+
+For instance, given an `api.yaml`:
 
 ```yaml
 openapi: "3.0.0"
@@ -595,6 +753,23 @@ components:
           type: int
 ```
 
+And a `cfg.yaml`:
+
+```yaml
+package: onlymodels
+output: only-models.gen.go
+generate:
+  models: true
+```
+
+And a `generate.go`:
+
+```go
+package onlymodels
+
+//go:generate go run github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen -config cfg.yaml api.yaml
+```
+
 This would then generate:
 
 ```go
