From 84d4b0c52962c99fe67942f8fe724a407c6513b9 Mon Sep 17 00:00:00 2001
From: Alex Ling <hkalexling@gmail.com>
Date: Sun, 20 Dec 2020 14:31:17 +0000
Subject: [PATCH] Switch to redoc and update API description

---
 src/routes/api.cr          | 22 ++++++++++++++--------
 src/routes/main.cr         |  4 ++--
 src/views/api.html.ecr     | 14 ++++++++++++++
 src/views/swagger.html.ecr | 22 ----------------------
 4 files changed, 30 insertions(+), 32 deletions(-)
 create mode 100644 src/views/api.html.ecr
 delete mode 100644 src/views/swagger.html.ecr

diff --git a/src/routes/api.cr b/src/routes/api.cr
index 8abf089..05f3d04 100644
--- a/src/routes/api.cr
+++ b/src/routes/api.cr
@@ -6,6 +6,8 @@ require "koa"
 class APIRouter < Router
   @@api_json : String?
 
+  API_VERSION = "0.1.0"
+
   macro s(fields)
     {
       {% for field in fields %}
@@ -15,16 +17,20 @@ class APIRouter < Router
   end
 
   def initialize
-    Koa.init "Mango API", version: MANGO_VERSION, desc: <<-MD
-      ## Terminalogies
+    Koa.init "Mango API", version: API_VERSION, desc: <<-MD
+    # A Word of Caution
 
-      - Entry: An entry is a `cbz`/`cbr` file in your library. Depending on how you organize your manga collection, an entry can contain a chapter, a volume or even an entire manga.
-      - Title: A title contains a list of entries and optionally some sub-titles. For example, your can have a title to store a manga, and  it contains a list of sub-titles representing the volumes in the manga. Each sub-title would then contain a list of entries representing the chapters in the volume.
-      - Library: The library is a collection of the top-level titles, and it does not contain entries (though the titles do). A Mango instance can only have one library.
+    This API was designed for internal use only, and the design doesn't comply with the resources convention of a RESTful API. Because of this, most of the API endpoints listed here will soon be updated and removed in future versions of Mango, so use them at your own risk!
 
-      ## Authentication
+    # Authentication
 
-      All endpoints require authentication. After logging in, your session ID would be stored as a cookie named `mango-sessid-#{Config.current.port}`, which can be used to authenticate the API access. Note that all admin API enpoints (`/api/admin/...`) require the logged in user to have admin access.
+    All endpoints require authentication. After logging in, your session ID would be stored as a cookie named `mango-sessid-#{Config.current.port}`, which can be used to authenticate the API access. Note that all admin API endpoints (`/api/admin/...`) require the logged in user to have admin access.
+
+    # Terminologies
+
+    - Entry: An entry is a `cbz`/`cbr` file in your library. Depending on how you organize your manga collection, an entry can contain a chapter, a volume or even an entire manga.
+    - Title: A title contains a list of entries and optionally some sub-titles. For example, you can have a title to store a manga, and it contains a list of sub-titles representing the volumes in the manga. Each sub-title would then contain a list of entries representing the chapters in the volume.
+    - Library: The library is a collection of top-level titles, and it does not contain entries (though the titles do). A Mango instance can only have one library.
     MD
 
     Koa.cookie_auth "cookie", "mango-sessid-#{Config.current.port}"
@@ -635,7 +641,7 @@ class APIRouter < Router
       end
     end
 
-    Koa.describe "Returns the image dimention of all pages in an entry"
+    Koa.describe "Returns the image dimensions of all pages in an entry"
     Koa.path "tid", desc: "A title ID"
     Koa.path "eid", desc: "An entry ID"
     Koa.response 200, ref: "$dimensionResult"
diff --git a/src/routes/main.cr b/src/routes/main.cr
index bf54c0f..cb919cf 100644
--- a/src/routes/main.cr
+++ b/src/routes/main.cr
@@ -114,8 +114,8 @@ class MainRouter < Router
       end
     end
 
-    get "/swagger" do |env|
-      render "src/views/swagger.html.ecr"
+    get "/api" do |env|
+      render "src/views/api.html.ecr"
     end
   end
 end
diff --git a/src/views/api.html.ecr b/src/views/api.html.ecr
new file mode 100644
index 0000000..5bfdfa4
--- /dev/null
+++ b/src/views/api.html.ecr
@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta name="X-UA-Compatible" content="IE=edge">
+    <title>Mango API Documentation</title>
+    <meta name="description" content="Mango - Manga Server and Web Reader">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+  </head>
+  <body>
+    <redoc spec-url="/openapi.json"></redoc>
+    <script src="https://cdn.jsdelivr.net/npm/redoc/bundles/redoc.standalone.js"></script>
+  </body>
+</html>
diff --git a/src/views/swagger.html.ecr b/src/views/swagger.html.ecr
deleted file mode 100644
index 9babf87..0000000
--- a/src/views/swagger.html.ecr
+++ /dev/null
@@ -1,22 +0,0 @@
-<!DOCTYPE html>
-<html>
-  <head>
-    <meta charset="utf-8">
-    <meta name="X-UA-Compatible" content="IE=edge">
-    <title>Mango Swagger-UI</title>
-    <meta name="description" content="Mango - Manga Server and Web Reader">
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@3/swagger-ui.css">
-  </head>
-  <body>
-    <div id="swagger"></div>
-
-    <script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js" charset="UTF-8"></script>
-    <script>
-      SwaggerUIBundle({
-        url: "/openapi.json",
-        dom_id: '#swagger',
-      });
-    </script>
-  </body>
-</html>