@bazo/openapi-client-generator 3.0.13

package/skills/integrate-playwright-client/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: integrate-playwright-client
+description: >
+  Use the generated playwright-mode client for E2E API testing in CI/CD.
+  Covers peer dependencies (zod, @playwright/test), instantiation from
+  Playwright APIRequestContext fixture, calling async operation methods,
+  ApiResponse<T> assertions, and Zod-validated response bodies. Load when
+  importing or using a generated playwright-mode client file in tests.
+type: framework
+library: openapi-client-generator
+library_version: "3.0.0"
+requires:
+  - generate-client
+sources:
+  - "bazo/openapi-client-generator:src/modes/playwright/index.ts"
+  - "bazo/openapi-client-generator:src/modes/playwright/query.ts"
+  - "bazo/openapi-client-generator:src/modes/playwright/mutation.ts"
+---
+
+This skill builds on generate-client. Read it first for CLI usage.
+
+# Integrate Playwright Client
+
+## Setup
+
+Install peer dependencies:
+
+```bash
+npm install -D zod @playwright/test
+```
+
+Use the generated client in a Playwright test:
+
+```typescript
+import { test, expect } from "@playwright/test";
+import { TestApi } from "./generated/TestApi";
+
+test("list tasks returns 200", async ({ request }) => {
+  const api = new TestApi(request);
+  const result = await api.listTasks({ page: 1, limit: 10 });
+  expect(result.status).toBe(200);
+  expect(result.data.items.length).toBeGreaterThan(0);
+});
+```
+
+The constructor takes a single argument: Playwright's `APIRequestContext`, available from the `{ request }` test fixture.
+
+## Core Patterns
+
+### Query operation with parameters
+
+```typescript
+test("get task by id", async ({ request }) => {
+  const api = new TestApi(request);
+  const result = await api.getTask({ taskId: "123" });
+  expect(result.status).toBe(200);
+  expect(result.data.id).toBe("123");
+});
+```
+
+All operations are async methods on the client class. Path, query, and header parameters are passed as a single params object.
+
+### Mutation operation with request body
+
+```typescript
+test("create a task", async ({ request }) => {
+  const api = new TestApi(request);
+  const result = await api.createTask({
+    body: { title: "Test task", status: "todo" },
+  });
+  expect(result.status).toBe(201);
+  expect(result.data.title).toBe("Test task");
+});
+```
+
+Mutations accept a `body` property in the params object. The body is Zod-validated before sending.
+
+### Assert on ApiResponse structure
+
+```typescript
+test("check response shape", async ({ request }) => {
+  const api = new TestApi(request);
+  const result = await api.healthCheck();
+  expect(result).toEqual(
+    expect.objectContaining({
+      status: 200,
+      data: expect.any(Object),
+      headers: expect.any(Object),
+      url: expect.any(String),
+    }),
+  );
+});
+```
+
+Every operation returns `ApiResponse<T>` with `data`, `status`, `headers`, and `url`.
+
+## Common Mistakes
+
+### CRITICAL Missing peer dependencies
+
+Wrong:
+
+```bash
+npm install -D @playwright/test
+# Generated file fails: Cannot find module 'zod'
+```
+
+Correct:
+
+```bash
+npm install -D zod @playwright/test
+```
+
+The generated playwright-mode file imports both `zod` and `@playwright/test`. Both must be installed.
+
+Source: src/modes/playwright/index.ts generateImports
+
+### CRITICAL Passing a URL string instead of APIRequestContext
+
+Wrong:
+
+```typescript
+const api = new TestApi("https://api.example.com");
+```
+
+Correct:
+
+```typescript
+test("api test", async ({ request }) => {
+  const api = new TestApi(request);
+});
+```
+
+The playwright client constructor takes an `APIRequestContext`, not a base URL. The request context comes from Playwright's `{ request }` test fixture, which handles base URL configuration via `playwright.config.ts`.
+
+Source: src/modes/playwright/index.ts generateClient
+
+### HIGH Editing the generated file directly
+
+Wrong:
+
+```typescript
+// Adding a helper method directly in TestApi.ts
+export class TestApi {
+  // ...generated methods...
+  async customHelper() { /* hand-written */ }
+}
+```
+
+Correct:
+
+```typescript
+// Create a wrapper in a separate file
+import { TestApi } from "./generated/TestApi";
+
+class ExtendedTestApi extends TestApi {
+  async customHelper() { /* hand-written */ }
+}
+```
+
+The generated output is meant to be regenerated from the spec. Manual edits are overwritten on the next generation run.
+
+Source: maintainer interview
+
+See also: generate-client/SKILL.md — CLI usage for regenerating the client

package/skills/integrate-swift-client/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: integrate-swift-client
+description: >
+  Use the generated Swift client in an iOS or macOS application. Covers
+  adding the .swift file to Xcode, instantiation with URL and URLSession,
+  async/await operation calls, Codable struct schemas, ApiResponse<T>,
+  APIError enum handling, and Sendable conformance. Load when importing
+  or using a generated swift-mode client file.
+type: framework
+library: openapi-client-generator
+library_version: "3.0.0"
+requires:
+  - generate-client
+sources:
+  - "bazo/openapi-client-generator:src/modes/swift/index.ts"
+  - "bazo/openapi-client-generator:src/modes/swift/query.ts"
+  - "bazo/openapi-client-generator:src/modes/swift/mutation.ts"
+---
+
+This skill builds on generate-client. Read it first for CLI usage.
+
+# Integrate Swift Client
+
+## Setup
+
+No external dependencies required. The generated file uses only Foundation.
+
+Add the generated `.swift` file to your Xcode project, then instantiate:
+
+```swift
+let api = ApiClient(baseURL: URL(string: "https://api.example.com")!)
+```
+
+The constructor signature is:
+
+```swift
+init(baseURL: URL, session: URLSession = .shared)
+```
+
+## Core Patterns
+
+### Call a query operation
+
+```swift
+let result = try await api.listTasks(page: 1, limit: 10)
+print(result.data.items) // [Task]
+print(result.status) // 200
+```
+
+All operations are `async throws` functions. Query parameters map to function parameters with defaults for optional ones.
+
+### Call a mutation operation
+
+```swift
+let newTask = CreateTaskRequest(title: "Build feature", status: "todo", description: nil)
+let result = try await api.createTask(body: newTask)
+print(result.data.id) // created task ID
+```
+
+Mutations take a `body` parameter typed as the corresponding Codable request struct.
+
+### Handle API errors
+
+```swift
+do {
+    let result = try await api.getTask(taskId: "nonexistent")
+} catch let error as APIError {
+    switch error {
+    case .badResponse(let statusCode, let data):
+        print("HTTP \(statusCode)")
+    case .decodingError(let error):
+        print("Decode failed: \(error)")
+    }
+}
+```
+
+Non-success responses throw `APIError.badResponse`. Decoding failures throw `APIError.decodingError`.
+
+### Use a custom URLSession
+
+```swift
+let config = URLSessionConfiguration.default
+config.httpAdditionalHeaders = ["Authorization": "Bearer \(token)"]
+let session = URLSession(configuration: config)
+let api = ApiClient(baseURL: URL(string: "https://api.example.com")!, session: session)
+```
+
+## Common Mistakes
+
+### HIGH Providing String instead of URL for baseURL
+
+Wrong:
+
+```swift
+let api = ApiClient(baseURL: "https://api.example.com")
+```
+
+Correct:
+
+```swift
+let api = ApiClient(baseURL: URL(string: "https://api.example.com")!)
+```
+
+The constructor parameter is typed as `URL`, not `String`. Use `URL(string:)` which returns an optional — force-unwrap only for known-good URLs.
+
+Source: src/modes/swift/index.ts generateClient
+
+### HIGH Not using async/await for operations
+
+Wrong:
+
+```swift
+let result = api.getTask(taskId: "123")
+```
+
+Correct:
+
+```swift
+let result = try await api.getTask(taskId: "123")
+```
+
+All generated operations are `async throws` functions. They must be called with `try await` from an async context.
+
+Source: src/modes/swift/query.ts
+
+### HIGH Editing the generated file directly
+
+Wrong:
+
+```swift
+// Adding a custom method directly in ApiClient.swift
+class ApiClient: @unchecked Sendable {
+    // ...generated code...
+    func customMethod() async throws { /* hand-written */ }
+}
+```
+
+Correct:
+
+```swift
+// Extend in a separate file
+extension ApiClient {
+    func customMethod() async throws { /* hand-written */ }
+}
+```
+
+The generated output is meant to be regenerated from the spec. Manual edits are overwritten on the next generation run. Use Swift extensions in a separate file for custom methods.
+
+Source: maintainer interview
+
+See also: generate-client/SKILL.md — CLI usage for regenerating the client