sofa-api 0.11.2 → 0.12.0

package/README.md

@@ -20,47 +20,14 @@ Here's complete example with no dependency on frameworks, but also integratable
 ```js
 import http from 'http';
 import getStream from 'get-stream';
-import { createSofaRouter } from 'sofa-api';
-
-const invokeSofa = createSofaRouter({
-  basePath: '/api',
-  schema,
-});
+import { useSofa } from 'sofa-api';
 
-const server = http.createServer(async (req, res) => {
-  try {
-    const response = await invokeSofa({
-      method: req.method,
-      url: req.url,
-      body: JSON.parse(await getStream(req)),
-      contextValue: {
-        req,
-      },
-    });
-    if (response) {
-      const headers = {
-        'Content-Type': 'application/json',
-      };
-      if (response.statusMessage) {
-        res.writeHead(response.status, response.statusMessage, headers);
-      } else {
-        res.writeHead(response.status, headers);
-      }
-      if (response.type === 'result') {
-        res.end(JSON.stringify(response.body));
-      }
-      if (response.type === 'error') {
-        res.end(JSON.stringify(response.error));
-      }
-    } else {
-      res.writeHead(404);
-      res.end();
-    }
-  } catch (error) {
-    res.writeHead(500);
-    res.end(JSON.stringify(error));
-  }
-});
+const server = http.createServer(
+  useSofa({
+    basePath: '/api',
+    schema,
+  })
+);
 ```
 
 Another example with builtin express-like frameworks support
@@ -302,6 +269,7 @@ Thanks to GraphQL's Type System Sofa is able to generate OpenAPI (Swagger) defin
 
 ```ts
 import { useSofa, OpenAPI } from 'sofa-api';
+import { writeFileSync } from 'fs';
 
 const openApi = OpenAPI({
   schema,
@@ -325,13 +293,14 @@ app.use(
 );
 
 // writes every recorder route
-openApi.save('./swagger.yml');
+writeFileSync('./swagger.json', JSON.stringify(openApi.get(), null, 2));
 ```
 
 OpenAPI (Swagger) with Bearer Authentication
 
 ```ts
 import { useSofa, OpenAPI } from 'sofa-api';
+import { writeFileSync } from 'fs';
 
 const openApi = OpenAPI({
   schema,
@@ -368,6 +337,66 @@ app.use(
   })
 );
 
+// writes every recorder route
+writeFileSync('./swagger.json', JSON.stringify(openApi.get(), null, 2));
+```
+
+OpenAPI (Swagger) with custom tags, summary and description  
+
+```ts
+const openApi = OpenAPI({
+  schema,
+  info: {
+    title: 'Example API',
+    version: '3.0.0',
+  },
+    tags: [
+        {
+            name: 'Book',
+            description: 'Book related operations',
+        },
+        {
+            name: 'Author',
+            description: 'Author related operations',
+        },
+    ],
+});
+```
+
+```ts
+@Resolver(Book)
+export class BookResolver {
+    @Query(() => Book, { description: 'Get book by id' }) // custom summary tag
+    getBookById(@Arg('id', () => Int) id: number) {
+        return 'book';
+    }
+}
+```
+
+```ts
+const routes: SofaConfig['routes'] = {
+    'Query.getBookById': {
+        method: 'POST',
+        path: '/book/:id',
+        tags: ['Book'],
+        description: 'This is a custom detailed description for getBookById',
+    },
+}
+
+const createSofaMiddleware = (
+    schema: GraphQLSchema,
+    openApi: ReturnType<typeof OpenAPI>,
+    basePath = ''
+): ReturnType<typeof useSofa> => {
+    return useSofa({
+        routes,
+        basePath,
+        schema,
+        onRoute(info) {
+            openApi.addRoute(info, { basePath });
+        },
+    });
+};
 // writes every recorder route
 openApi.save('./swagger.yml');
 ```

package/index.d.ts

@@ -1,38 +1,3 @@
-/// <reference types="node" />
-import * as http from 'http';
-import type { ContextValue } from './types';
 import type { SofaConfig } from './sofa';
 export { OpenAPI } from './open-api';
-declare type Request = http.IncomingMessage & {
-    method: string;
-    url: string;
-    originalUrl?: string;
-    body?: any;
-};
-declare type NextFunction = (err?: any) => void;
-declare type Middleware = (req: Request, res: http.ServerResponse, next: NextFunction) => unknown;
-export declare type ContextFn = (init: {
-    req: any;
-    res: any;
-}) => ContextValue;
-export declare function isContextFn(context: any): context is ContextFn;
-interface SofaMiddlewareConfig extends SofaConfig {
-    context?: ContextValue | ContextFn;
-}
-export declare function useSofa({ context, ...config }: SofaMiddlewareConfig): Middleware;
-export declare function createSofaRouter(config: SofaConfig): (request: {
-    method: string;
-    url: string;
-    body: any;
-    contextValue: ContextValue;
-}) => Promise<({
-    type: "result";
-    status: number;
-    statusMessage?: string | undefined;
-    body: any;
-} | {
-    type: "error";
-    status: number;
-    statusMessage?: string | undefined;
-    error: any;
-}) | null>;
+export declare function useSofa(config: SofaConfig): import("@whatwg-node/server").ServerAdapter<unknown, import("itty-router").Router<import("itty-router").Request & Request, {}>>;