API home page (#198)

* API home page

* Try to move swagger outside the onload

* Rollback swagger to 4.5.2

* Revert "Try to move swagger outside the onload"

This reverts commit 86e6db4.

* Switch to inline styling

* Fix broken twemoji url

* Add a noscript

* Add CORS headers

* typo

* OpenAPI formatting

.gitignore

@@ -22,7 +22,7 @@ dist
 cache
 
 # CSS from quilt-bulma
-public/assets/css
+public/assets/css/style*
 
 # Generated function files
 functions/*

package.json

@@ -15,6 +15,7 @@
 		"@astrojs/rss": "^1.2.1",
 		"@astrojs/sitemap": "^1.4.0",
 		"@types/luxon": "^3.3.3",
+		"@types/swagger-ui": "^3.52.4",
 		"astro": "1.6.14",
 		"astro-i18next": "1.0.0-beta.12",
 		"astro-purgecss": "^1.3.2",
@@ -31,6 +32,7 @@
 		"rehype-autolink-headings": "^6.1.1",
 		"rollup": "^3.29.4",
 		"sass": "^1.69.4",
+		"swagger-ui": "4.5.2",
 		"typescript": "^4.9.5"
 	},
 	"dependencies": {

public/_headers

@@ -0,0 +1,2 @@
+/api/*:
+    Access-Control-Allow-Origin: *

public/api/openapi.yaml

@@ -0,0 +1,147 @@
+openapi: 3.0.0
+info:
+  title: Quilt Meta API
+  version: "2024-04-08"
+  description: |
+    This is the Quilt Website API. You can use it to inspect various information about our project.
+    
+    # Versioning
+    | Version | Support commitment | End of support | Sunset |
+    |---------|--------------------|----------------|--------|
+    | v1      | 6 months           | TBD            | TBD    |
+    
+    # User agents
+    Please make sure to set a proper [user agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) when accessing this service. We may block empty or non-personalized user agents.
+
+servers:
+  - url: https://quiltmc.org/api
+    description: Production server
+  - url: https://quiltmc-testing.xyz/api
+    description: Testing server, may not always be available
+
+paths:
+  /v1/incompatible-mods.json:
+    get:
+      summary: Get various information about mods known to be incompatible with Quilt.
+      tags:
+        - v1
+      responses:
+        '200':
+          description: |
+            List of incompatible mods.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/IncompatibleModV1'
+
+  /v1/download-latest-installer/{architecture}:
+    parameters:
+      - name: architecture
+        in: path
+        required: true
+        description: >
+          The architecture to query:
+          
+          - `windows-x86_64`
+          
+          - `windows-i686`
+          
+          - `windows-aarch64`
+          
+          - `java-universal` (jar installer)
+        schema:
+          type: string
+          example: "windows-x86_64"
+          enum:
+            - windows-x86_64
+            - windows-i686
+            - windows-aarch64
+            - java-universal
+    get:
+      summary: Download the latest installer for the given architecture.
+      tags:
+        - v3
+      responses:
+        '307':
+          description: Redirects to the maven artifact.
+        '404':
+          description: The specified architecture is not supported.
+
+components:
+  schemas:
+    IncompatibleModV1:
+      type: object
+      required: [ids, name, type, status, tracking, icon]
+      properties:
+        ids:
+          type: array
+          items:
+            type: string
+          description: The mod IDs that are known to be incompatible with Quilt.
+          example: ["modid1", "modid2"]
+
+        name:
+            type: string
+            description: The name of the mod.
+            example: "Example Mod"
+
+        type:
+          type: string
+          description: >
+            The type of incompatibility:
+            
+            - `GAME`: Breaks the game in an unrecoverable way.
+            
+            - `OTHERS`: Breaks other mods in an unrecoverable way.
+            
+            - `SELF`: Causes non-fatal errors or broken features in the mod itself.
+            
+            - `WORKAROUND`: Requires a workaround to function properly. Please see the attached note.
+          enum:
+            - GAME
+            - OTHERS
+            - SELF
+            - WORKAROUND
+          example: "GAME"
+
+        status:
+          type: string
+          description: >
+            The status of the incompatibility:
+            
+            - `UNKNOWN`: The status of the incompatibility is unknown, due to a lack of report or the inability for us to find it.
+            
+            - `WONT_FIX`: The incompatibility is known, but the mod authors have stated they won't fix it.
+            
+            - `IN_PROGRESS`: The incompatibility is known, and the mod authors are working on a fix.
+            
+            - `BLOCKED`: The incompatibility is known, but the fix is blocked by an external factor.
+            
+            - `NO_ANSWER`: The mod authors have not responded yet to the report.
+            
+            - `ON_HOLD`: The incompatibility is known, but the mod authors wish to wait before implementing a fix.
+          enum:
+            - UNKNOWN
+            - WONT_FIX
+            - IN_PROGRESS
+            - BLOCKED
+            - NO_ANSWER
+            - ON_HOLD
+          example: "IN_PROGRESS"
+
+        tracking:
+          type: string
+          description: The tracking URL for the report. Set to `UNKNOWN` if the tracking URL is not available.
+          example: "https://example.com/tracking"
+
+        icon:
+          type: string
+          description: The URL to the mod's icon. Solely for display purposes.
+          example: "https://example.com/icon.png"
+
+        note:
+            type: string
+            description: A note about the incompatibility. May not be present.
+            example: "This mod made an oopsie and used fabric internals."

src/components/setpieces/HtmlHead.astro

@@ -104,7 +104,7 @@ const titleFormatted = t("title-formatted", {
 	</noscript>
 	<script
 		async
-		src="https://twemoji.maxcdn.com/v/latest/twemoji.min.js"
+		src="https://unpkg.com/twemoji@14.0.2/dist/twemoji.min.js"
 		crossorigin="anonymous"
 	></script>
 	<link href="/assets/prism-material-dark.css" rel="stylesheet" />

src/components/setpieces/NavBar.astro

@@ -127,6 +127,9 @@ const { style = "is-dark" } = Astro.props as Props;
 					>
 						{t("nav-page-staff-resources")}
 					</NavLink>
+					<NavLink href="/api" icon="fas fa-plug-circle-plus">
+						{t("nav-page-api-home")}
+					</NavLink>
 					<NavLink href={localizePath("/legal")} icon="fas fa-scale-balanced">
 						{t("nav-page-legal")}
 					</NavLink>

src/locales/en/common.flt

@@ -55,6 +55,7 @@ nav-page-template-mod = {-template-mod}
 nav-page-legal = Legal
 nav-page-donate = Donate
 nav-page-changelog = Changelog
+nav-page-api-home = API Home
 
 button-close = Close
 button-discord = {-discord}

src/pages/api.astro

@@ -0,0 +1,30 @@
+---
+import Base from "@layouts/Base.astro";
+import swaggerCss from "swagger-ui/dist/swagger-ui.css?raw";
+import swaggerDarkCss from "../styles/swagger-dark.css?raw";
+---
+
+<script>
+    import SwaggerUI from 'swagger-ui';
+
+    window.addEventListener("load", () => {
+        window.ui = SwaggerUI({
+            url: '/api/openapi.yaml',
+            dom_id: '#swagger-ui',
+            deepLinking: true,
+        });
+    });
+</script>
+<style is:inline>
+    pre.version {
+        background-color: inherit !important;
+    }
+</style>
+<style is:inline set:html={swaggerCss}></style>
+<style is:inline set:html={swaggerDarkCss}></style>
+
+<Base content={{title: "Quilt API Index", description: "Index for the Quilt Website API"}}>
+    <div id="swagger-ui"></div>
+
+    <noscript><p class="p-3">Please enable javascript</p></noscript>
+</Base>