improve openapi meta

Author: pi0

routes/_health.ts

@@ -1,3 +1,9 @@
+defineRouteMeta({
+  openAPI: {
+    description: "Service health check endpoint (should return 200 OK).",
+  },
+});
+
 export default eventHandler(() => {
   // const runtimeConfig = useRuntimeConfig();
   // const res = await $fetch.raw("/meta", {

routes/index.ts

@@ -1,5 +1,11 @@
 import { renderHTML } from "openapi-renderer";
 
+defineRouteMeta({
+  openAPI: {
+    description: "API documentation for Ungh.",
+  },
+});
+
 export default eventHandler(
   () =>
     renderHTML({

routes/orgs/[owner]/index.ts

@@ -1,5 +1,19 @@
 import type { GithubOrg } from "~types";
 
+defineRouteMeta({
+  openAPI: {
+    description: "GitHub organization information.",
+    parameters: [
+      {
+        name: "owner",
+        in: "path",
+        required: true,
+        schema: { type: "string", example: "unjs" },
+      },
+    ],
+  },
+});
+
 export default eventHandler(async (event) => {
   const org = await ghFetch(`orgs/${event.context.params.owner}`);
 

routes/orgs/[owner]/repos.ts

@@ -1,5 +1,19 @@
 import type { GithubRepo } from "~types";
 
+defineRouteMeta({
+  openAPI: {
+    description: "GitHub organization repositories overview.",
+    parameters: [
+      {
+        name: "owner",
+        in: "path",
+        required: true,
+        schema: { type: "string", example: "unjs" },
+      },
+    ],
+  },
+});
+
 export default eventHandler(async (event) => {
   // TODO: Do pagination
   const rawRepos = await ghFetch(

routes/repos/[owner]/[repo]/branches/index.ts

@@ -1,5 +1,25 @@
 import type { GitHubBranches } from "~types";
 
+defineRouteMeta({
+  openAPI: {
+    description: "Get all the branches of a repository.",
+    parameters: [
+      {
+        name: "owner",
+        in: "path",
+        required: true,
+        schema: { type: "string", example: "unjs" },
+      },
+      {
+        name: "repo",
+        in: "path",
+        required: true,
+        schema: { type: "string", example: "ofetch" },
+      },
+    ],
+  },
+});
+
 export default eventHandler(async (event) => {
   const repo = `${event.context.params.owner}/${event.context.params.repo}`;
   const res = await ghFetch(`/repos/${repo}/branches`);

routes/repos/[owner]/[repo]/contributors.ts

@@ -1,5 +1,25 @@
 import type { GithubContributor } from "~types";
 
+defineRouteMeta({
+  openAPI: {
+    description: "Get repository contributors.",
+    parameters: [
+      {
+        name: "owner",
+        in: "path",
+        required: true,
+        schema: { type: "string", example: "unjs" },
+      },
+      {
+        name: "repo",
+        in: "path",
+        required: true,
+        schema: { type: "string", example: "ofetch" },
+      },
+    ],
+  },
+});
+
 export default eventHandler(async (event) => {
   const res = await ghRepoContributors(
     `${event.context.params.owner}/${event.context.params.repo}`,

routes/repos/[owner]/[repo]/files/[branch]/[...path].ts

@@ -1,6 +1,12 @@
 // import { hash } from "ohash";
 // import type { GithubFileData } from "~types";
 
+defineRouteMeta({
+  openAPI: {
+    description: "(disabled - redirects to raw.githubusercontent.com)",
+  },
+});
+
 export default eventHandler(async (event) => {
   const repo = `${event.context.params.owner}/${event.context.params.repo}`;
   const ref = `${event.context.params.branch}/${event.context.params.path}`;

routes/repos/[owner]/[repo]/files/[branch]/index.ts

@@ -1,5 +1,11 @@
 import type { GithubFile } from "~types";
 
+defineRouteMeta({
+  openAPI: {
+    description: "(disabled - redirects to raw.githubusercontent.com)",
+  },
+});
+
 export default eventHandler(async (event) => {
   const repo = `${event.context.params.owner}/${event.context.params.repo}`;
   const res = await ghRepoFiles(repo, event.context.params.branch);

routes/repos/[owner]/[repo]/index.ts

@@ -1,5 +1,25 @@
 import type { GithubRepo } from "~types";
 
+defineRouteMeta({
+  openAPI: {
+    description: "Get repository readme file on main branch (not cached).",
+    parameters: [
+      {
+        name: "owner",
+        in: "path",
+        required: true,
+        schema: { type: "string", example: "unjs" },
+      },
+      {
+        name: "repo",
+        in: "path",
+        required: true,
+        schema: { type: "string", example: "ofetch" },
+      },
+    ],
+  },
+});
+
 export default eventHandler(async (event) => {
   const rawRepo = await ghRepo(
     `${event.context.params.owner}/${event.context.params.repo}`,

routes/repos/[owner]/[repo]/readme.ts

@@ -1,5 +1,25 @@
 const GH_RAW_URL = "https://raw.githubusercontent.com";
 
+defineRouteMeta({
+  openAPI: {
+    description: "Get repository readme file on main branch (not cached).",
+    parameters: [
+      {
+        name: "owner",
+        in: "path",
+        required: true,
+        schema: { type: "string", example: "unjs" },
+      },
+      {
+        name: "repo",
+        in: "path",
+        required: true,
+        schema: { type: "string", example: "ofetch" },
+      },
+    ],
+  },
+});
+
 export default cachedEventHandler(
   async (event) => {
     const repo = `${event.context.params.owner}/${event.context.params.repo}`;