blsmedia/bot
2
0
Fork 0
Code Issues Activity

📝 Introduce auto generate API doc

Browse Source
This commit is contained in:
Baptiste Arnaud
2022-11-22 17:30:20 +01:00
parent 04af489119
commit 11695efb57
60 changed files with 1480 additions and 914 deletions
Download Patch File Download Diff File Expand all files Collapse all files

118
apps/docs/docs/api.mdx
View File

@@ -1,118 +0,0 @@
import { Required, Optional, Tag } from '../src/js/api-helpers.js'
# API documentation
Each request must be authenticated with an API key using the Bearer Token method. You can obtain an API key for your account by going to your user settings.
The API is a work in progress. The current version is dedicated to Automation services that wish to implement a native Typebot integration.
## Endpoints
### <Tag color="green">GET</Tag> /api/users/me
Get authenticated user information:
```bash title="Try it yourself"
curl -i -X GET https://typebot.io/api/users/me \
-H 'Authorization: Bearer ${TOKEN}'
```
```json title="Response 200 OK"
{ "id": "userid", "email": "user@email.com" }
```
### <Tag color="green">GET</Tag> /api/typebots
List user's typebots:
```bash title="Try it yourself"
curl -i -X GET https://typebot.io/api/typebots \
-H 'Authorization: Bearer ${TOKEN}'
```
```json title="Response 200 OK"
{
"typebots": [
{
"name": "My typebot 1",
"id": "typebot1"
},
{
"name": "My typebot 2",
"id": "typebot2"
}
]
}
```
### <Tag color="green">GET</Tag> /api/typebots/<Tag>typebotId</Tag>/webhookBlocks
List webhook blocks in a typebot. These are the blocks you can register a Webhook URL:
```bash title="Try it yourself"
curl -i -X GET https://typebot.io/api/typebots/$TYPEBOT_ID/webhookBlocks \
-H 'Authorization: Bearer ${TOKEN}'
```
```json title="Response 200 OK"
{
"blocks": [
{
"blockId": "blockId",
"name": "Group #2 > blockId",
"url": "https://my-webhook.com/webhook"
}
]
}
```
### <Tag color="green">GET</Tag> /api/typebots/<Tag>typebotId</Tag>/blocks/<Tag>blockId</Tag>/sampleResult
Get a sample of what the webhook body will look like when triggered
```bash title="Try it yourself"
curl -i -X GET https://typebot.io/api/typebots/$TYPEBOT_ID/blocks/$BLOCK_ID/sampleResult \
-H 'Authorization: Bearer ${TOKEN}'
```
### <Tag color="orange">POST</Tag> /api/typebots/<Tag>typebotId</Tag>/blocks/<Tag>blockId</Tag>/subscribeWebhook
Subscribe the block to a specified webhook URL
```bash title="Try it yourself"
curl -i -X POST https://typebot.io/api/typebots/$TYPEBOT_ID/blocks/$BLOCK_ID/subscribeWebhook \
-H 'Authorization: Bearer ${TOKEN}'\
--header 'Content-Type: application/json' \
--data '{"url": "https://domain.com/my-webhook"}'
```
```json title="Response 200 OK"
{
"message": "success"
}
```
#### JSON body data
<hr />
**url** <Required />
The url you want to subscribe to.
<hr />
### <Tag color="orange">POST</Tag> /api/typebots/<Tag>typebotId</Tag>/blocks/<Tag>blockId</Tag>/unsubscribeWebhook
Unsubscribe the current webhook on block
```bash title="Try it yourself"
curl -i -X POST https://typebot.io/api/typebots/$TYPEBOT_ID/blocks/$BLOCK_ID/unsubscribeWebhook \
-H 'Authorization: Bearer ${TOKEN}'\
```
```json title="Response 200 OK"
{
"message": "success"
}
```

22
apps/docs/docusaurus.config.js
View File

@@ -1,10 +1,10 @@
/** @type {import('@docusaurus/types').DocusaurusConfig} */
/** @type {import('@docusaurus/types').Config} */
module.exports = {
title: 'Typebot docs',
tagline: 'Get to Typebot next level with its documentation',
url: 'https://docs.typebot.io',
baseUrl: '/',
onBrokenLinks: 'warn',
onBrokenLinks: 'throw',
onBrokenMarkdownLinks: 'warn',
favicon: 'img/favicon.png',
organizationName: 'baptisteArno', // Usually your GitHub org/user name.
@@ -16,6 +16,16 @@ module.exports = {
src: 'img/logo.svg',
},
items: [
{
href: '/',
label: 'Docs',
position: 'left',
},
{
href: '/api',
label: 'API Reference',
position: 'left',
},
{
href: 'https://github.com/baptisteArno/typebot.io/tree/main/apps/docs',
label: 'Contribute',
@@ -73,14 +83,18 @@ module.exports = {
],
},
colorMode: {
disableSwitch: false,
respectPrefersColorScheme: true,
},
},
presets: [
[
'@docusaurus/preset-classic',
'docusaurus-preset-openapi',
/** @type {import('docusaurus-preset-openapi').Options} */
{
api: {
path: 'openapi',
routeBasePath: '/api',
},
docs: {
sidebarPath: require.resolve('./sidebars.js'),
routeBasePath: '/',

34
apps/docs/openapi/authenticate.md Normal file
View File

@@ -0,0 +1,34 @@
---
sidebar_position: 1
slug: /
---
# Authentication
Every API resources are protected, and therefore require that you authenticate using an API token.
## Generate a token
1. Navigate to your typebot dashboard (https://app.typebot.io/typebots)
2. Click on Settings & Members > My account
3. Under the "API tokens" section, click on "Create"
4. Give it a name, then click on "Create token"
5. Copy your token.
<img
src="/img/api/authentication/generateToken.png"
width="900"
alt="Generate token"
/>
## Use your token
You can authenticate by adding an `Authorization` header to all your HTTP calls. The Authorization header is formatted as such: `Authorization: Bearer <token>` (replace `<token>` with your token previously generated).
Example:
```sh
curl -L -X GET 'https://app.typebot.io/api/typebots/:typebotId/results' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer myAwesomeToken'
```

391
apps/docs/openapi/builder.json Normal file
View File

@@ -0,0 +1,391 @@
{
"openapi": "3.0.3",
"info": {
"title": "Builder API",
"version": "1.0.0"
},
"servers": [
{
"url": "https://app.typebot.io/api/v1"
}
],
"paths": {
"/typebots/{typebotId}/results": {
"get": {
"operationId": "query.results.getResults",
"summary": "List results",
"tags": [
"Results"
],
"security": [
{
"Authorization": []
}
],
"parameters": [
{
"name": "typebotId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": true,
"schema": {
"type": "string",
"pattern": "^[0-9]{1,3}$"
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"typebotId": {
"type": "string"
},
"variables": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": [
"id",
"name",
"value"
],
"additionalProperties": false
}
},
"isCompleted": {
"type": "boolean"
},
"hasStarted": {
"type": "boolean",
"nullable": true
},
"isArchived": {
"type": "boolean",
"nullable": true
}
},
"required": [
"id",
"createdAt",
"updatedAt",
"typebotId",
"variables",
"isCompleted",
"hasStarted",
"isArchived"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"answers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"createdAt": {
"type": "string",
"format": "date-time"
},
"resultId": {
"type": "string"
},
"blockId": {
"type": "string"
},
"groupId": {
"type": "string"
},
"variableId": {
"type": "string",
"nullable": true
},
"content": {
"type": "string"
},
"storageUsed": {
"type": "number",
"nullable": true
}
},
"required": [
"createdAt",
"resultId",
"blockId",
"groupId",
"variableId",
"content",
"storageUsed"
],
"additionalProperties": false
}
}
},
"required": [
"answers"
],
"additionalProperties": false
}
]
}
},
"nextCursor": {
"anyOf": [
{
"not": {}
},
{
"type": "string"
}
],
"nullable": true
}
},
"required": [
"results"
],
"additionalProperties": false
}
}
}
},
"default": {
"$ref": "#/components/responses/error"
}
}
},
"delete": {
"operationId": "mutation.results.deleteResults",
"summary": "Delete results",
"tags": [
"Results"
],
"security": [
{
"Authorization": []
}
],
"parameters": [
{
"name": "typebotId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "ids",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {}
}
},
"default": {
"$ref": "#/components/responses/error"
}
}
}
},
"/typebots/{typebotId}/results/{resultId}/logs": {
"get": {
"operationId": "query.results.getResultLogs",
"summary": "List result logs",
"tags": [
"Results"
],
"security": [
{
"Authorization": []
}
],
"parameters": [
{
"name": "typebotId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "resultId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"logs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"resultId": {
"type": "string"
},
"status": {
"type": "string"
},
"description": {
"type": "string"
},
"details": {
"type": "string",
"nullable": true
}
},
"required": [
"id",
"createdAt",
"resultId",
"status",
"description",
"details"
],
"additionalProperties": false
}
}
},
"required": [
"logs"
],
"additionalProperties": false
}
}
}
},
"default": {
"$ref": "#/components/responses/error"
}
}
}
}
},
"components": {
"securitySchemes": {
"Authorization": {
"type": "http",
"scheme": "bearer"
}
},
"responses": {
"error": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string"
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
],
"additionalProperties": false
}
}
},
"required": [
"message",
"code"
],
"additionalProperties": false
}
}
}
}
}
},
"externalDocs": {
"url": "https://docs.typebot.io/api"
}
}

6
apps/docs/package.json
View File

@@ -12,13 +12,15 @@
"serve": "docusaurus serve",
"write-translations": "docusaurus write-translations",
"write-heading-ids": "docusaurus write-heading-ids",
"update-search": "docker run -it --rm --env-file=.env -e \"CONFIG=$(cat docsearch-scrapper-config.json | jq -r tostring)\" algolia/docsearch-scraper"
"update-search": "docker run -it --rm --env-file=.env -e \"CONFIG=$(cat docsearch-scrapper-config.json | jq -r tostring)\" algolia/docsearch-scraper",
"builder:generate:openapi": "tsx --tsconfig ../builder/tsconfig.json ../builder/src/utils/server/generateOpenApi.ts"
},
"dependencies": {
"@docusaurus/core": "2.2.0",
"@docusaurus/preset-classic": "2.2.0",
"@docusaurus/theme-search-algolia": "2.2.0",
"@docusaurus/theme-common": "2.2.0",
"docusaurus-preset-openapi": "^0.6.3",
"react": "17.0.2",
"react-dom": "17.0.2",
"@mdx-js/react": "1.6.22",
@@ -42,7 +44,9 @@
},
"devDependencies": {
"@algolia/client-search": "4.14.2",
"@docusaurus/types": "^2.2.0",
"@types/react": "18.0.25",
"tsx": "3.12.1",
"typescript": "4.9.3",
"webpack": "5.75.0"
}

34
apps/docs/src/css/custom.css
View File

@@ -76,3 +76,37 @@ details {
transform: rotate(90deg);
}
}
.theme-api-markdown > table {
font-size: 90%;
}
.theme-api-markdown table table {
width: calc(100% - 16px) !important;
margin-left: 16px;
}
.theme-api-markdown table table {
border-left: 3px solid var(--ifm-table-stripe-background);
}
.theme-api-markdown table table tr:first-child {
border-top: 0;
}
.theme-api-markdown table thead tr {
border-bottom-width: 3px;
border-top: 0;
}
.theme-api-markdown table tr {
background-color: transparent;
}
.theme-api-markdown table th {
border: 0;
}
.theme-api-markdown table td {
border: 0;
}

BIN
apps/docs/static/img/api/authentication/generateToken.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 361 KiB