docs: switch openapi docs (#215)

* update openapi

* update

* fix: shared_vocabulary is not a required file

* docs: improve docs

crates/tabby-download/src/lib.rs

@@ -64,7 +64,8 @@ pub async fn download_model(model_id: &str, prefer_local_file: bool) -> Result<(
             "ctranslate2/shared_vocabulary.txt",
             prefer_local_file,
         )
-        .await?;
+        .await
+        .unwrap_or(());
     cache_info
         .download(model_id, "ctranslate2/model.bin", prefer_local_file)
         .await?;

crates/tabby/src/serve/completions.rs

@@ -21,6 +21,7 @@ pub struct CompletionRequest {
     #[deprecated]
     prompt: Option<String>,
 
+    /// Language identifier, full list is maintained at
     /// https://code.visualstudio.com/docs/languages/identifiers
     #[schema(example = "python")]
     language: Option<String>,
@@ -55,7 +56,13 @@ pub struct CompletionResponse {
 #[utoipa::path(
     post,
     path = "/v1/completions",
-    request_body = CompletionRequest ,
+    request_body = CompletionRequest,
+    operation_id = "completion",
+    tag = "v1",
+    responses(
+        (status = 200, description = "Success", body = CompletionResponse, content_type = "application/json"),
+        (status = 400, description = "Bad Request")
+    )
 )]
 pub async fn completion(
     State(state): State<Arc<CompletionState>>,

crates/tabby/src/serve/events.rs

@@ -6,10 +6,13 @@ use utoipa::ToSchema;
 
 #[derive(Serialize, Deserialize, ToSchema, Clone, Debug)]
 pub struct LogEventRequest {
+    /// Event type, should be `view` or `select`.
     #[schema(example = "view")]
     #[serde(rename = "type")]
     event_type: String,
+
     completion_id: String,
+
     choice_index: u32,
 }
 
@@ -17,6 +20,12 @@ pub struct LogEventRequest {
     post,
     path = "/v1/events",
     request_body = LogEventRequest,
+    tag = "v1",
+    operation_id = "event",
+    responses(
+        (status = 200, description = "Success"),
+        (status = 400, description = "Bad Request")
+    )
 )]
 pub async fn log_event(Json(request): Json<LogEventRequest>) -> StatusCode {
     if request.event_type == "view" {

crates/tabby/src/serve/mod.rs

@@ -18,6 +18,11 @@ use crate::fatal;
 
 #[derive(OpenApi)]
 #[openapi(
+    info(title="Tabby Server", description = "OpenAPI documentation for [tabby](https://github.com/TabbyML/tabby), a self-hosted AI coding assistant. ![tabby stars](https://img.shields.io/github/stars/TabbyML/tabby?style=social)", license(name = "Apache 2.0", url="https://github.com/TabbyML/tabby/blob/main/LICENSE")),
+    servers(
+        (url = "https://app.tabbyml.com/api/workspace/tabbyml/tabby", description = "Local server"),
+        (url = "http://localhost:8080", description = "Local server"),
+    ),
     paths(events::log_event, completions::completion,),
     components(schemas(
         events::LogEventRequest,

website/docusaurus.config.js

@@ -35,7 +35,7 @@ const config = {
 
   presets: [
     [
-      'classic',
+      'docusaurus-preset-openapi',
       /** @type {import('@docusaurus/preset-classic').Options} */
       ({
         docs: {
@@ -45,6 +45,10 @@ const config = {
           editUrl:
             'https://github.com/TabbyML/tabby/edit/main/website',
         },
+        api: {
+          path: "static/openapi.json",
+          routeBasePath: "/api"
+        },
         blog: {
           showReadingTime: true,
           // Please change this to your repo.
@@ -57,23 +61,6 @@ const config = {
         },
       }),
     ],
-    [
-      'redocusaurus',
-      ({
-        // Plugin Options for loading OpenAPI files
-        specs: [
-          {
-            spec: 'static/openapi.json',
-            route: '/api/',
-          },
-        ],
-        // Theme Options for modifying how redoc renders them
-        theme: {
-          // Change with your site colors
-          primaryColor: '#2e8555',
-        },
-      }),
-    ],
   ],
 
   themeConfig:
@@ -167,7 +154,7 @@ const config = {
         },
       };
     },
-  ]
+  ],
 };
 
 module.exports = config;

website/package.json

@@ -19,12 +19,13 @@
     "@mdx-js/react": "^1.6.22",
     "autoprefixer": "^10.4.14",
     "clsx": "^1.2.1",
+    "docusaurus-preset-openapi": "^0.6.4",
     "postcss": "^8.4.24",
     "prism-react-renderer": "^1.3.5",
     "react": "^17.0.2",
     "react-dom": "^17.0.2",
-    "redocusaurus": "^1.6.2",
-    "tailwindcss": "^3.3.2"
+    "tailwindcss": "^3.3.2",
+    "url": "^0.11.0"
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "2.4.1"

website/src/css/custom.css

@@ -32,3 +32,31 @@
   --ifm-color-primary-lightest: #4fddbf;
   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
 }
+
+.post a {
+  display: flex;
+}
+
+.post a::after {
+  content: "post";
+  margin-left: auto;
+  display: inline-block;
+  position: relative;
+  top: 1px;
+  margin-right: -6px;
+  padding: 3px 6px;
+  border: 1px solid var(--ifm-color-warning);
+  border-radius: 3px;
+  color: black;
+  background: var(--ifm-color-warning);
+  text-transform: uppercase;
+  font-size: 10px;
+  line-height: 10px;
+  height: 10px;
+  font-weight: 600;
+}
+
+[data-theme='dark'] .post a::after {
+  color: var(--ifm-color-warning);
+  background: none;
+}

website/static/openapi.json

@@ -1 +1 @@
-{"openapi":"3.0.3","info":{"title":"tabby","description":"","license":{"name":""},"version":"0.1.0"},"paths":{"/v1/completions":{"post":{"tags":["completions"],"operationId":"completion","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompletionRequest"}}},"required":true},"responses":{}}},"/v1/events":{"post":{"tags":["events"],"operationId":"log_event","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogEventRequest"}}},"required":true},"responses":{}}}},"components":{"schemas":{"Choice":{"type":"object","required":["index","text"],"properties":{"index":{"type":"integer","format":"int32","minimum":0.0},"text":{"type":"string"}}},"CompletionRequest":{"type":"object","properties":{"prompt":{"type":"string","deprecated":true,"example":"def fib(n):","nullable":true},"language":{"type":"string","description":"https://code.visualstudio.com/docs/languages/identifiers","example":"python","nullable":true},"segments":{"allOf":[{"$ref":"#/components/schemas/Segments"}],"nullable":true}}},"CompletionResponse":{"type":"object","required":["id","choices"],"properties":{"id":{"type":"string"},"choices":{"type":"array","items":{"$ref":"#/components/schemas/Choice"}}}},"LogEventRequest":{"type":"object","required":["type","completion_id","choice_index"],"properties":{"type":{"type":"string","example":"view"},"completion_id":{"type":"string"},"choice_index":{"type":"integer","format":"int32","minimum":0.0}}},"Segments":{"type":"object","required":["prefix"],"properties":{"prefix":{"type":"string","description":"Content that appears before the cursor in the editor window.","example":"def fib(n):\n    "},"suffix":{"type":"string","description":"Content that appears after the cursor in the editor window.","example":"\n        return fib(n - 1) + fib(n - 2)","nullable":true}}}}}}
+{"openapi":"3.0.3","info":{"title":"Tabby Server","description":"OpenAPI documentation for [tabby](https://github.com/TabbyML/tabby), a self-hosted AI coding assistant. ![tabby stars](https://img.shields.io/github/stars/TabbyML/tabby?style=social)","license":{"name":"Apache 2.0","url":"https://github.com/TabbyML/tabby/blob/main/LICENSE"},"version":"0.1.0"},"servers":[{"url":"https://app.tabbyml.com/api/workspace/tabbyml/tabby","description":"Local server"},{"url":"http://localhost:8080","description":"Local server"}],"paths":{"/v1/completions":{"post":{"tags":["v1"],"operationId":"completion","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompletionRequest"}}},"required":true},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompletionResponse"}}}},"400":{"description":"Bad Request"}}}},"/v1/events":{"post":{"tags":["v1"],"operationId":"event","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogEventRequest"}}},"required":true},"responses":{"200":{"description":"Success"},"400":{"description":"Bad Request"}}}}},"components":{"schemas":{"Choice":{"type":"object","required":["index","text"],"properties":{"index":{"type":"integer","format":"int32","minimum":0.0},"text":{"type":"string"}}},"CompletionRequest":{"type":"object","properties":{"prompt":{"type":"string","deprecated":true,"example":"def fib(n):","nullable":true},"language":{"type":"string","description":"Language identifier, full list is maintained at\nhttps://code.visualstudio.com/docs/languages/identifiers","example":"python","nullable":true},"segments":{"allOf":[{"$ref":"#/components/schemas/Segments"}],"nullable":true}}},"CompletionResponse":{"type":"object","required":["id","choices"],"properties":{"id":{"type":"string"},"choices":{"type":"array","items":{"$ref":"#/components/schemas/Choice"}}}},"LogEventRequest":{"type":"object","required":["type","completion_id","choice_index"],"properties":{"type":{"type":"string","description":"Event type, should be `view` or `select`.","example":"view"},"completion_id":{"type":"string"},"choice_index":{"type":"integer","format":"int32","minimum":0.0}}},"Segments":{"type":"object","required":["prefix"],"properties":{"prefix":{"type":"string","description":"Content that appears before the cursor in the editor window.","example":"def fib(n):\n    "},"suffix":{"type":"string","description":"Content that appears after the cursor in the editor window.","example":"\n        return fib(n - 1) + fib(n - 2)","nullable":true}}}}}}