apigen-ts 0.0.3 → 0.1.0

package/readme.md

@@ -1,4 +1,4 @@
-# OpenAPI TypeScript client generator
+# apigen-ts
 
 <div align="center">
 
@@ -10,15 +10,24 @@
 
 </div>
 
+<div align="center">
+  <img src="./logo.svg" alt="apigen-ts logo" height="80" />
+</div>
+
+<div align="center">
+  TypeScript api client generator from OpenAPI specification
+</div>
+
 ## Features
 
-- Generates ready to use ApiClient with types (using `fetch`)
+- Generates ready to use `ApiClient` with types (using `fetch`)
 - Single output file, minimal third-party code
 - Load schema from JSON / YAML, locally and remote
 - Ability to customize `fetch` with your custom function
-- Uses `type` instead of `interface`, so no problem with declaration merging
+- Uses `type` instead of `interface`, no problem with declaration merging
 - Automatic formating with Prettier
-- Parses dates automatically
+- Can parse dates from date-time format (`--parse-dates` flag)
+- Support OpenAPI v2, v3, v3.1
 
 ## Install
 
@@ -32,16 +41,18 @@ yarn install -D apigen-ts
 
 ```sh
 # From url
-yarn apigen-ts https://petstore3.swagger.io/api/v3/openapi.json ./api-generated.ts
+yarn apigen-ts https://petstore3.swagger.io/api/v3/openapi.json ./api-client.ts
 
 # From file
-yarn apigen-ts ./openapi.json ./api-generated.ts
+yarn apigen-ts ./openapi.json ./api-client.ts
 ```
 
+Run `yarn apigen-ts --help` for more options. See examples of generated clients [here](./examples/).
+
 ### Import
 
 ```typescript
-import { ApiClient } from "./api-generated"
+import { ApiClient } from "./api-client"
 
 const api = new ApiClient({
   baseUrl: "https://example.com/api",
@@ -58,8 +69,8 @@ await api.pet.getPetById(1) // -> Pet
 // GET /pet/findByStatus?status=sold
 await api.pet.findPetsByStatus({ status: "sold" }) // -> Pets[]
 
-// PUT /user/{username}
-await api.user.updateUser("username", { firstName: "John" }) // second arg is body with type User
+// PUT /user/{username}; second arg body with type User
+await api.user.updateUser("username", { firstName: "John" })
 ```
 
 ## Advanced
@@ -73,6 +84,31 @@ api.Config.headers = { Authorization: token }
 await api.protectedRoute.get() // here authenticated
 ```
 
+### NodeJS API
+
+Create file like `apigen.mjs` with content:
+
+```javascript
+import { apigen } from "apigen-ts"
+
+await apigen({
+  source: "https://petstore3.swagger.io/api/v3/openapi.json",
+  output: "./api-client.ts",
+  // everything below is optional
+  name: "MyApiClient", // default "ApiClient"
+  parseDates: true, // default false
+  resolveName(ctx, op, proposal) {
+    // proposal is [string, string] which represents module.funcName
+    if (proposal[0] === "users") return // will use default proposal
+
+    const [a, b] = op.name.split("/").slice(3, 5) // eg. /api/v1/store/items/search
+    return [a, `${op.method}_${b}`] // [store, 'get_items'] -> apiClient.store.get_items()
+  },
+})
+```
+
+Then run with: `node apigen.mjs`
+
 ## Useful for development
 
 - https://ts-ast-viewer.com