Add README.md (#5)

Author: zachkirsch

.prettierrc

@@ -0,0 +1,4 @@
+{
+  "printWidth": 80,
+  "trailingComma": "all"
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Alex Johansson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,96 @@
+<div align="center">
+  <h1>trpc-openapi-2</h1>
+  <a href="https://www.npmjs.com/package/trpc-openapi-2"><img src="https://img.shields.io/npm/v/trpc-openapi-2.svg?style=flat&color=brightgreen" target="_blank" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-black" /></a>
+</div>
+
+---
+
+## Generate an OpenAPI spec from your tRPC server, in one line of code
+
+### Step 1: Install `trpc-openapi-2`
+
+```bash
+# npm
+npm install trpc-openapi-2
+
+# yarn
+yarn install trpc-openapi-2
+
+# pnpm
+pnpm install trpc-openapi-2
+```
+
+### Step 2: Generate OpenAPI spec
+
+```typescript
+import { trpcToOpenApi } from "trpc-openapi-2";
+
+// generate OpenAPI spec
+const openApiSpec = trpcToOpenApi({
+  apiTitle: "Your API",
+  apiVersion: "1.0.0",
+  basePath: "/trpc",
+  router: trpcRouter,
+});
+
+// express example: serve openapi spec at /openapi.json
+app.get("/openapi.json", (_, res) => res.json(openApiSpec));
+```
+
+## Configuring the OpenAPI spec
+
+### Excluding certain procedures
+
+#### Step 1: Add `OpenApiMeta` to your `initTRPC` call:
+
+```typescript
+import { OpenApiMeta } from "trpc-openapi-2";
+
+const t = initTRPC.meta<OpenApiMeta>().create();
+```
+
+#### Step 2: Use .meta() in your procedure
+
+```typescript
+const router = t.router({
+  myProcedure: t.procedure
+    .meta({ openapi: { ignore: true } }) /* 👈 */
+    .input(...
+});
+```
+
+## Comparison
+
+[`trpc-openapi`](https://github.com/trpc/trpc-openapi)
+and its new fork [`trpc-to-openapi`](https://github.com/mcampa/trpc-to-openapi)
+are the two relevant libraries.
+
+### They modify your API by adding new endpoints
+
+**These other libraries do not simply generate an OpenAPI spec for your existing tRPC server.**
+They add _new endpoints_ to your server and then generate an OpenAPI spec for those new endpoints.
+
+For example:
+
+```typescript
+// trpc-openapi example:
+
+export const appRouter = t.router({
+  sayHello: t.procedure
+
+    // trpc-openapi adds a new endpoint to your server (`/say-hello`)
+    // and the generated OpenAPI spec only includes this new `/say-hello`
+    // endpoint, not the original `/trpc/sayHello` procedure
+    .meta({ /* 👉 */ openapi: { method: "GET", path: "/say-hello" } }),
+});
+```
+
+In comparison, `trpc-openapi-2` simply generates an OpenAPI spec for your existing tRPC API,
+without modifying your API functionality at all.
+
+### They require you to use `.meta()` on every procedure
+
+These libraries require that you add `.meta()` to every procedure that you
+want included in your OpenAPI spec. In comparison, with `trpc-openapi-2` you can generate
+the full OpenAPI spec by calling `trpcToOpenApi()` without modifying your procedures at all.

eslint.config.mjs

@@ -5,5 +5,5 @@ import tseslint from "typescript-eslint";
 
 export default tseslint.config(
   eslint.configs.recommended,
-  tseslint.configs.strict
+  tseslint.configs.strict,
 );

package.json

@@ -1,11 +1,12 @@
 {
   "name": "trpc-openapi-2",
   "version": "1.0.0",
-  "description": "Generate an OpenAPI spec from your trpc server, in one line of code",
+  "description": "Generate an OpenAPI spec from your tRPC server, in one line of code",
   "main": "lib/index.js",
   "files": [
     "lib",
-    "!lib/**/__test__"
+    "!lib/**/__test__",
+    "README.md"
   ],
   "scripts": {
     "build": "tsc",

src/__test__/trpcToOpenApi.test.ts

@@ -19,6 +19,7 @@ describe("trpcToOpenApi", () => {
     const openApiSpec = trpcToOpenApi({
       apiTitle: "My API",
       apiVersion: "1.0",
+      basePath: "",
       router,
     });
 
@@ -89,6 +90,7 @@ describe("trpcToOpenApi", () => {
     const openApiSpec = trpcToOpenApi({
       apiTitle: "My API",
       apiVersion: "1.0",
+      basePath: "",
       router,
     });
 

src/index.ts

@@ -1,6 +1,3 @@
-import { trpcToOpenApi } from "./trpcToOpenApi";
-
-export { trpcToOpenApi };
-export default trpcToOpenApi;
+export { trpcToOpenApi } from "./trpcToOpenApi";
 
 export { type OpenApiMeta } from "./meta";

src/trpcToOpenApi.ts

@@ -14,12 +14,12 @@ import { entries } from "./utils";
 export function trpcToOpenApi({
   apiTitle,
   apiVersion,
-  basePath = "",
+  basePath,
   router,
 }: {
   apiTitle: string;
   apiVersion: string;
-  basePath?: string;
+  basePath: string;
   router: AnyTRPCRouter;
 }): OpenAPIV3_1.Document {
   return {