docs: add options and tips

aspida · Jun 25, 2020 · 0c9cbcf · 0c9cbcf
1 parent 5b92af1
commit 0c9cbcf
Show file tree

Hide file tree

Showing 3 changed files with 240 additions and 16 deletions.
diff --git a/README.md b/README.md
@@ -262,6 +262,15 @@ import api from "../apis/$api"
   </tbody>
 </table>
 
+## Options of aspida.config.js
+
+| Option        | Type    | Default                     | Description                                           |
+| ------------- | ------- | --------------------------- | ----------------------------------------------------- |
+| input         | string  | "apis", "server/api", "api" | Specifies the endpoint type definition root directory |
+| baseURL       | string  | ""                          | Specify baseURL of the request                        |
+| trailingSlash | boolean | false                       | Append `/` to the request URL                         |
+| outputEachDir | boolean | false                       | Generate `$api.ts` in each endpoint directory         |
+
 ## Tips
 
 ### Change the directory where type definition file is placed to other than apis
@@ -324,7 +333,7 @@ export type Methods = {
 
     reqBody: {
       name: string
-      icon: ArrayBuffer
+      icon: Blob
     }
 
     resBody: {
@@ -346,7 +355,7 @@ import api from "../apis/$api"
   const user = await client.v1.users.$post({
     body: {
       name: "taro",
-      icon: imageBuffer
+      icon: imageBlob
     }
   })
   console.log(user)
@@ -442,10 +451,76 @@ $ npx openapi2aspida --build
 
 [Docs of openapi2aspida](https://github.com/aspidajs/openapi2aspida)
 
+### Define endpoints that contain special characters
+
+Special characters are encoded as percent-encoding in the file name  
+Example `":"` -> `"%3A"`
+
+`apis/foo%3Abar.ts`
+
+```ts
+export type Methods = {
+  get: {
+    resBody: string
+  }
+}
+```
+
+With clients, `"%3A"` -> `"_3A"`
+
+`src/index.ts`
+
+```typescript
+import aspida from "@aspida/axios"
+import api from "../apis/$api"
+;(async () => {
+  const client = api(aspida())
+
+  const message = await client.foo_3Abar.$get()
+  console.log(message)
+  // req -> GET: /foo%3Abar (= /foo:bar)
+})()
+```
+
+### Import only some endpoints
+
+If you don't need to use all of `apis/$api.ts` , you can split them up and import only part of them  
+`outputEachDir` option generates `$api.ts` in each endpoint directory  
+`$api.ts` will not be generated under the directory containing the path variable
+
+`aspida.config.js`
+
+```js
+module.exports = {
+  input: "apis",
+  outputEachDir: true
+}
+```
+
+Import only `$api.ts` of the endpoint you want to use and put it into Object
+
+`src/index.ts`
+
+```typescript
+import aspida from "@aspida/axios"
+import api0 from "../apis/v1/foo/$api"
+import api1 from "../apis/v2/bar/$api"
+;(async () => {
+  const aspidaClient = aspida()
+  const client = {
+    foo: api0(aspidaClient),
+    bar: api1(aspidaClient)
+  }
+
+  const message = await client.bar._id(1).$get()
+  // req -> GET: /foo
+})()
+```
+
 ## Support
 
 <a href="https://twitter.com/solufa2020">
-  <img src="https://aspidajs.github.io/aspida/assets/images/twitter.svg" width="65" alt="Twitter" />
+  <img src="https://aspidajs.github.io/aspida/assets/images/twitter.svg" width="50" alt="Twitter" />
 </a>
 
 ## License

diff --git a/packages/aspida/README.md b/packages/aspida/README.md
@@ -262,6 +262,15 @@ import api from "../apis/$api"
   </tbody>
 </table>
 
+## Options of aspida.config.js
+
+| Option        | Type    | Default                     | Description                                           |
+| ------------- | ------- | --------------------------- | ----------------------------------------------------- |
+| input         | string  | "apis", "server/api", "api" | Specifies the endpoint type definition root directory |
+| baseURL       | string  | ""                          | Specify baseURL of the request                        |
+| trailingSlash | boolean | false                       | Append `/` to the request URL                         |
+| outputEachDir | boolean | false                       | Generate `$api.ts` in each endpoint directory         |
+
 ## Tips
 
 ### Change the directory where type definition file is placed to other than apis
@@ -324,7 +333,7 @@ export type Methods = {
 
     reqBody: {
       name: string
-      icon: ArrayBuffer
+      icon: Blob
     }
 
     resBody: {
@@ -346,7 +355,7 @@ import api from "../apis/$api"
   const user = await client.v1.users.$post({
     body: {
       name: "taro",
-      icon: imageBuffer
+      icon: imageBlob
     }
   })
   console.log(user)
@@ -442,10 +451,76 @@ $ npx openapi2aspida --build
 
 [Docs of openapi2aspida](https://github.com/aspidajs/openapi2aspida)
 
+### Define endpoints that contain special characters
+
+Special characters are encoded as percent-encoding in the file name  
+Example `":"` -> `"%3A"`
+
+`apis/foo%3Abar.ts`
+
+```ts
+export type Methods = {
+  get: {
+    resBody: string
+  }
+}
+```
+
+With clients, `"%3A"` -> `"_3A"`
+
+`src/index.ts`
+
+```typescript
+import aspida from "@aspida/axios"
+import api from "../apis/$api"
+;(async () => {
+  const client = api(aspida())
+
+  const message = await client.foo_3Abar.$get()
+  console.log(message)
+  // req -> GET: /foo%3Abar (= /foo:bar)
+})()
+```
+
+### Import only some endpoints
+
+If you don't need to use all of `apis/$api.ts` , you can split them up and import only part of them  
+`outputEachDir` option generates `$api.ts` in each endpoint directory  
+`$api.ts` will not be generated under the directory containing the path variable
+
+`aspida.config.js`
+
+```js
+module.exports = {
+  input: "apis",
+  outputEachDir: true
+}
+```
+
+Import only `$api.ts` of the endpoint you want to use and put it into Object
+
+`src/index.ts`
+
+```typescript
+import aspida from "@aspida/axios"
+import api0 from "../apis/v1/foo/$api"
+import api1 from "../apis/v2/bar/$api"
+;(async () => {
+  const aspidaClient = aspida()
+  const client = {
+    foo: api0(aspidaClient),
+    bar: api1(aspidaClient)
+  }
+
+  const message = await client.bar._id(1).$get()
+  // req -> GET: /foo
+})()
+```
+
 ## Support
 
 <a href="https://twitter.com/solufa2020">
-  <img src="https://aspidajs.github.io/aspida/assets/images/twitter.svg" width="65" alt="Twitter" />
+  <img src="https://aspidajs.github.io/aspida/assets/images/twitter.svg" width="50" alt="Twitter" />
 </a>
 
 ## License

diff --git a/packages/aspida/docs/ja/README.md b/packages/aspida/docs/ja/README.md
@@ -234,34 +234,42 @@ import api from "../apis/$api"
       <td></td>
       <td>
         aspida のルーティングに必要な
-        <code>$api.ts</code> を生成します。
+        <code>$api.ts</code> を生成
       </td>
     </tr>
     <tr>
       <td nowrap><code>--config</code><br /><code>-c</code></td>
       <td><code>string</code></td>
       <td><code>"aspida.config.js"</code></td>
-      <td>設定ファイルまでのパスを指定します。</td>
+      <td>設定ファイルまでのパスを指定</td>
     </tr>
     <tr>
       <td nowrap><code>--watch</code><br /><code>-w</code></td>
       <td></td>
       <td></td>
       <td>
-        監視モードを有効にします。<br />
-        API のエンドポイントとなるファイルの増減に合わせて
-        <code>$api.ts</code> を再生成します。
+        監視モードを有効にし、API のエンドポイントとなるファイルの増減に合わせて
+        <code>$api.ts</code> を再生成
       </td>
     </tr>
     <tr>
       <td nowrap><code>--version</code><br /><code>-v</code></td>
       <td></td>
       <td></td>
-      <td>aspida のバージョンを表示します。</td>
+      <td>aspida のバージョンを表示</td>
     </tr>
   </tbody>
 </table>
 
+## aspida.config.js のオプション
+
+| Option        | Type    | Default                     | Description                                        |
+| ------------- | ------- | --------------------------- | -------------------------------------------------- |
+| input         | string  | "apis", "server/api", "api" | エンドポイントの型定義ルートディレクトリを指定     |
+| baseURL       | string  | ""                          | リクエスト時の baseURL を指定                      |
+| trailingSlash | boolean | false                       | リクエスト URL の末尾に `/` を付与                 |
+| outputEachDir | boolean | false                       | `$api.ts` を各エンドポイントのディレクトリにも生成 |
+
 ## Tips
 
 ### 型定義ファイルを置くディレクトリを apis 以外に変更する
@@ -324,7 +332,7 @@ export type Methods = {
 
     reqBody: {
       name: string
-      icon: ArrayBuffer
+      icon: Blob
     }
 
     resBody: {
@@ -346,7 +354,7 @@ import api from "../apis/$api"
   const user = await client.v1.users.$post({
     body: {
       name: "taro",
-      icon: imageBuffer
+      icon: imageBlob
     }
   })
   console.log(user)
@@ -442,10 +450,76 @@ $ npx openapi2aspida --build
 
 [openapi2aspida ドキュメント](https://github.com/aspidajs/openapi2aspida)
 
+### 特殊文字を含む URL を定義する
+
+特殊文字はパーセントエンコーディングしてファイル名に指定する  
+例 `":"` -> `"%3A"`
+
+`apis/foo%3Abar.ts`
+
+```ts
+export type Methods = {
+  get: {
+    resBody: string
+  }
+}
+```
+
+クライアントでは `"%3A"` -> `"_3A"` となる
+
+`src/index.ts`
+
+```typescript
+import aspida from "@aspida/axios"
+import api from "../apis/$api"
+;(async () => {
+  const client = api(aspida())
+
+  const message = await client.foo_3Abar.$get()
+  console.log(message)
+  // req -> GET: /foo%3Abar (= /foo:bar)
+})()
+```
+
+### 一部のエンドポイントのみ import する
+
+`apis/$api.ts` の全てを使う必要がない場合、分割して一部のみ import できる  
+`outputEachDir` オプションで各エンドポイントのディレクトリに `$api.ts` が生成される  
+パス変数を含むディレクトリ配下に `$api.ts` は生成されない
+
+`aspida.config.js`
+
+```js
+module.exports = {
+  input: "apis",
+  outputEachDir: true
+}
+```
+
+使いたいエンドポイントの `$api.ts` のみを import してオブジェクトにまとめる
+
+`src/index.ts`
+
+```typescript
+import aspida from "@aspida/axios"
+import api0 from "../apis/v1/foo/$api"
+import api1 from "../apis/v2/bar/$api"
+;(async () => {
+  const aspidaClient = aspida()
+  const client = {
+    foo: api0(aspidaClient),
+    bar: api1(aspidaClient)
+  }
+
+  const message = await client.bar._id(1).$get()
+  // req -> GET: /foo
+})()
+```
+
 ## サポート
 
-<a href="https://twitter.com/solufa2020">
-  <img src="https://aspidajs.github.io/aspida/assets/images/twitter.svg" width="65" alt="Twitter" />
+<a href="https://twitter.com/m_mitsuhide">
+  <img src="https://aspidajs.github.io/aspida/assets/images/twitter.svg" width="50" alt="Twitter" />
 </a>
 
 ## ライセンス