From e26529e8d93830567f1e3882f92bc157b28b509e Mon Sep 17 00:00:00 2001 From: Zhiguang Chen Date: Sat, 22 Nov 2025 08:47:55 +0100 Subject: [PATCH 1/4] Enable blog --- blog/2025-11-22-welcome/index.md | 11 +++++++++++ docusaurus.config.ts | 18 +++++++++++++++--- 2 files changed, 26 insertions(+), 3 deletions(-) create mode 100644 blog/2025-11-22-welcome/index.md diff --git a/blog/2025-11-22-welcome/index.md b/blog/2025-11-22-welcome/index.md new file mode 100644 index 0000000..6c9e555 --- /dev/null +++ b/blog/2025-11-22-welcome/index.md @@ -0,0 +1,11 @@ +--- +slug: welcome +title: Welcome +--- + +TODO: + +- Introduce the background of API Studio: why and when this project was + initiated. +- What problems exist with current tools, what issues they failed to address, + and how API Studio provides a solution. diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 3cefcbb..71b08d4 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -43,7 +43,18 @@ const config: Config = { sidebarPath: './sidebars.ts', // Please change this to your repo. // Remove this to remove the "edit this page" links. - editUrl: 'https://github.com/hanlogy/api-studio/', + // editUrl: 'https://github.com/hanlogy/api-studio/', + }, + blog: { + showReadingTime: true, + feedOptions: { + type: ['rss', 'atom'], + xslt: true, + }, + // Useful options to enforce blogging best practices + onInlineTags: 'warn', + onInlineAuthors: 'warn', + onUntruncatedBlogPosts: 'warn', }, theme: { customCss: './src/css/custom.css', @@ -71,13 +82,14 @@ const config: Config = { position: 'left', label: 'Tutorial', }, + { to: '/blog', label: 'Blog', position: 'left' }, { - href: 'https://github.com/hanlogy/api-studio/issues', + href: 'https://github.com/hanlogy/app.api-studio/discussions', label: 'Support', position: 'left', }, { - href: 'https://github.com/hanlogy/api-studio', + href: 'https://github.com/hanlogy/app.api-studio', label: 'GitHub', position: 'right', }, From 73261408ffab4942dec9e6fabad9205145ad708d Mon Sep 17 00:00:00 2001 From: Zhiguang Chen Date: Mon, 24 Nov 2025 10:17:32 +0100 Subject: [PATCH 2/4] re organize the docs --- docs/configs/mock-servers/_category_.json | 8 +++ .../mock-servers/route-case-matchers.md | 57 +++++++++++++++++++ docs/configs/requests/_category_.json | 8 +++ docs/configs/{ => requests}/collection.md | 1 + docs/configs/{ => requests}/request.md | 1 + 5 files changed, 75 insertions(+) create mode 100644 docs/configs/mock-servers/_category_.json create mode 100644 docs/configs/mock-servers/route-case-matchers.md create mode 100644 docs/configs/requests/_category_.json rename docs/configs/{ => requests}/collection.md (99%) rename docs/configs/{ => requests}/request.md (99%) diff --git a/docs/configs/mock-servers/_category_.json b/docs/configs/mock-servers/_category_.json new file mode 100644 index 0000000..2e5a7b9 --- /dev/null +++ b/docs/configs/mock-servers/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Mock Servers", + "position": 3, + "link": { + "type": "generated-index", + "description": "Mock servers configs" + } +} diff --git a/docs/configs/mock-servers/route-case-matchers.md b/docs/configs/mock-servers/route-case-matchers.md new file mode 100644 index 0000000..de77a7e --- /dev/null +++ b/docs/configs/mock-servers/route-case-matchers.md @@ -0,0 +1,57 @@ +--- +sidebar_position: 2 +title: Case Matchers +--- + +# Case matchers + +Case matchers are used for the mock server to match the request context. + +We use the same naming as the +[Jest Asymmetric Matchers](https://jestjs.io/docs/expect#asymmetric-matchers) +and almost have the same behavior. + +## `anything()` + +`anything()` matches anything but `null`. + +```json title="case" +{ + "body": { + "name": "{{anything()}}" + } +} +``` + +## `any(type)` + +`any(type)` matches anything that is the given `type`. + +`type` includes: `Number`, `String`, `Array`, `Object` + +```json title="case" +{ + "body": { + "id": "{{any(Number)}}", + "name": "{{any(String)}}", + "accesses": "{{any(Array)}}" + } +} +``` + +## `arrayContaining(array)` + +`arrayContaining(array)` matches a received array which contains all of the +elements in the expected array. + +```json title="case" +{ + "body": { + "categories": "{{arrayContaining([1, 2])}}" + } +} +``` + +--- + +To Continue... diff --git a/docs/configs/requests/_category_.json b/docs/configs/requests/_category_.json new file mode 100644 index 0000000..8da8691 --- /dev/null +++ b/docs/configs/requests/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Requests", + "position": 2, + "link": { + "type": "generated-index", + "description": "Requests configs" + } +} diff --git a/docs/configs/collection.md b/docs/configs/requests/collection.md similarity index 99% rename from docs/configs/collection.md rename to docs/configs/requests/collection.md index d91aed3..8b8158b 100644 --- a/docs/configs/collection.md +++ b/docs/configs/requests/collection.md @@ -1,5 +1,6 @@ --- sidebar_position: 2 +title: Collection --- # Collection Config diff --git a/docs/configs/request.md b/docs/configs/requests/request.md similarity index 99% rename from docs/configs/request.md rename to docs/configs/requests/request.md index 7e88494..0e4cc77 100644 --- a/docs/configs/request.md +++ b/docs/configs/requests/request.md @@ -1,5 +1,6 @@ --- sidebar_position: 3 +title: Request --- # Request Config From 3342e5ed9484bb306307c151acba538426f8a893 Mon Sep 17 00:00:00 2001 From: Zhiguang Chen Date: Thu, 4 Dec 2025 14:14:24 +0100 Subject: [PATCH 3/4] Add features category to docs --- docs/configs/_category_.json | 2 +- docs/features/_category_.json | 7 +++ docs/features/api-client.md | 28 ++++++++++++ docs/features/mock-servers.md | 83 +++++++++++++++++++++++++++++++++++ docs/scripts/_category_.json | 2 +- docusaurus.config.ts | 2 +- 6 files changed, 121 insertions(+), 3 deletions(-) create mode 100644 docs/features/_category_.json create mode 100644 docs/features/api-client.md create mode 100644 docs/features/mock-servers.md diff --git a/docs/configs/_category_.json b/docs/configs/_category_.json index 9e03e67..49be94f 100644 --- a/docs/configs/_category_.json +++ b/docs/configs/_category_.json @@ -1,6 +1,6 @@ { "label": "Configs", - "position": 2, + "position": 3, "link": { "type": "generated-index", "description": "Workspace config files" diff --git a/docs/features/_category_.json b/docs/features/_category_.json new file mode 100644 index 0000000..6820fd3 --- /dev/null +++ b/docs/features/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Features", + "position": 2, + "link": { + "type": "generated-index" + } +} diff --git a/docs/features/api-client.md b/docs/features/api-client.md new file mode 100644 index 0000000..7b78a27 --- /dev/null +++ b/docs/features/api-client.md @@ -0,0 +1,28 @@ +--- +sidebar_position: 1 +title: API Client +--- + +# API Client + +The API Client is where you run HTTP requests defined in your workspace configs +and inspect the results. + +Instead of building requests through a UI, you describe them in JSON files +(`collections/*.json`) and let Api Studio execute them. This keeps your API +usage close to your code and easy to version-control. + +## What it does + +- Sends HTTP requests based on your request config: + - Method, URL, query, headers, body. + - Resolved with variables from workspace, environment, collection, and + request. +- Applies `requestMiddleware` (if present) before the request is sent: + - Last chance to modify the request. + - Optionally handle auth, logging, or custom workflows. +- Executes the request and shows: + - Status code and status text. + - Response headers. + - Response body. + - Timing information. diff --git a/docs/features/mock-servers.md b/docs/features/mock-servers.md new file mode 100644 index 0000000..ae9813c --- /dev/null +++ b/docs/features/mock-servers.md @@ -0,0 +1,83 @@ +--- +sidebar_position: 2 +title: Mock Servers +--- + +# Mock servers + +Mock servers let you describe local **HTTP/HTTPS** endpoints in JSON and get +dynamic, rule-based responses without a real backend. + +## Case-based routing + +Each route can define multiple **cases**. +The incoming request is matched against these cases (method, path, query, body, +etc.), and the first match decides the response. This makes it easy to model +different scenarios for the same endpoint. + +## Jest-style matchers + +Request matching supports a Jest-like syntax, such as: + +- `any(Constructor)` +- `stringMatching(...)` +- `stringContaining(...)` + +This lets you write expressive conditions (for example “any string containing +`foo`”) directly in your JSON config, without extra code. + +### Example + +```json +{ + "cases": [ + { + "request": { + "query": { + "name": "{{stringContaining('foo')}}" + } + }, + "response": { + "body": { + "result": "ok" + } + } + }, + { + "request": { + "body": { + "level": "{{any(Number)}}" + } + }, + "response": "@file:../data/welcome.json" + } + ] +} +``` + +## Flexible responses and proxying + +For a matched case you can: + +- Return an inline JSON response. +- Load the response from a file (for example `@file:../data/welcome.json`). +- Or **forward** the request to another server, acting as a lightweight proxy + server. + +This combination lets you mix mocked behaviour with real upstream services in a +single, versioned workspace. + +### Proxy Config Example + +```json +{ + "name": "AWS Sam Local", + "method": "GET", + "path": "aws", + "cases": [ + { + "forward": "https://localhost:3000" + } + ] +} +``` diff --git a/docs/scripts/_category_.json b/docs/scripts/_category_.json index 8a3acb5..2b33316 100644 --- a/docs/scripts/_category_.json +++ b/docs/scripts/_category_.json @@ -1,6 +1,6 @@ { "label": "Scripts", - "position": 3, + "position": 5, "link": { "type": "generated-index" } diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 71b08d4..b81b971 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -80,7 +80,7 @@ const config: Config = { type: 'docSidebar', sidebarId: 'tutorialSidebar', position: 'left', - label: 'Tutorial', + label: 'Docs', }, { to: '/blog', label: 'Blog', position: 'left' }, { From 9560d04b79dd0b2e421671b9b1f775ee708a18c5 Mon Sep 17 00:00:00 2001 From: Zhiguang Chen Date: Thu, 4 Dec 2025 14:25:35 +0100 Subject: [PATCH 4/4] change category names --- docs/configs/{requests => api-client}/_category_.json | 4 ++-- docs/configs/{requests => api-client}/collection.md | 2 +- docs/configs/{requests => api-client}/request.md | 0 docs/quickstart.md | 5 ----- 4 files changed, 3 insertions(+), 8 deletions(-) rename docs/configs/{requests => api-client}/_category_.json (51%) rename docs/configs/{requests => api-client}/collection.md (98%) rename docs/configs/{requests => api-client}/request.md (100%) diff --git a/docs/configs/requests/_category_.json b/docs/configs/api-client/_category_.json similarity index 51% rename from docs/configs/requests/_category_.json rename to docs/configs/api-client/_category_.json index 8da8691..8509b5f 100644 --- a/docs/configs/requests/_category_.json +++ b/docs/configs/api-client/_category_.json @@ -1,8 +1,8 @@ { - "label": "Requests", + "label": "API Client", "position": 2, "link": { "type": "generated-index", - "description": "Requests configs" + "description": "API client configs" } } diff --git a/docs/configs/requests/collection.md b/docs/configs/api-client/collection.md similarity index 98% rename from docs/configs/requests/collection.md rename to docs/configs/api-client/collection.md index 8b8158b..1cfd609 100644 --- a/docs/configs/requests/collection.md +++ b/docs/configs/api-client/collection.md @@ -90,5 +90,5 @@ All variables can be reassigned at run-time using `requestMiddleware.js`. ## `requests` -A list of request definitions. See [Request config](/docs/configs/request) for +A list of request definitions. See [Request config](/docs/configs/api-client/request) for details. diff --git a/docs/configs/requests/request.md b/docs/configs/api-client/request.md similarity index 100% rename from docs/configs/requests/request.md rename to docs/configs/api-client/request.md diff --git a/docs/quickstart.md b/docs/quickstart.md index 116bea2..7298b38 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -40,8 +40,3 @@ This file defines the workspace configuration. It must: Launch **Api Studio**, click **"Open Workspace..."**, and select the folder you just created. - -## 3. Next Steps - -Check out the [Configs](/docs/category/configs) to learn how to create workspace -config, collections, and requests.