sofa-api 0.12.0-alpha.0 → 0.13.0

package/README.md

@@ -150,7 +150,7 @@ Sofa allows you to cutomize the http method, path and response status. For examp
 ```typescript
 api.use(
   '/api',
-  sofa({
+  useSofa({
     schema,
     routes: {
       'Query.feed': { method: 'POST' },
@@ -341,6 +341,66 @@ app.use(
 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');
+```
+
 ## License
 
 [MIT](https://github.com/Urigo/sofa/blob/master/LICENSE) © Uri Goldshtein

package/index.js

@@ -9,7 +9,6 @@ const graphql = require('graphql');
 const ittyRouter = require('itty-router');
 const utils = require('@graphql-tools/utils');
 const paramCase = require('param-case');
-const uuid = require('uuid');
 const fetch = require('@whatwg-node/fetch');
 const colors = _interopDefault(require('ansi-colors'));
 const server = require('@whatwg-node/server');
@@ -114,20 +113,17 @@ class SubscriptionManager {
     }
     start(event, contextValue) {
         return tslib.__awaiter(this, void 0, void 0, function* () {
-            const id = uuid.v4();
+            const id = fetch.crypto.randomUUID();
             const name = event.subscription;
             if (!this.operations.has(name)) {
                 throw new Error(`Subscription '${name}' is not available`);
             }
-            const { document, operationName, variables } = this.operations.get(name);
             logger.info(`[Subscription] Start ${id}`, event);
             const result = yield this.execute({
                 id,
                 name,
                 url: event.url,
-                document,
-                operationName,
-                variables,
+                variables: event.variables,
                 contextValue,
             });
             if (typeof result !== 'undefined') {
@@ -166,9 +162,9 @@ class SubscriptionManager {
             }, contextValue);
         });
     }
-    execute({ id, document, name, url, operationName, variables, contextValue, }) {
+    execute({ id, name, url, variables, contextValue, }) {
         return tslib.__awaiter(this, void 0, void 0, function* () {
-            const variableNodes = this.operations.get(name).variables;
+            const { document, operationName, variables: variableNodes } = this.operations.get(name);
             const variableValues = variableNodes.reduce((values, variable) => {
                 const value = parseVariable({
                     value: variables[variable.variable.name.value],
@@ -178,7 +174,7 @@ class SubscriptionManager {
                 if (typeof value === 'undefined') {
                     return values;
                 }
-                return Object.assign(Object.assign({}, values), { [name]: value });
+                return Object.assign(Object.assign({}, values), { [variable.variable.name.value]: value });
             }, {});
             const execution = yield this.sofa.subscribe({
                 schema: this.sofa.schema,
@@ -301,12 +297,11 @@ function createRouter(sofa) {
     router.post('/webhook', (request, serverContext) => tslib.__awaiter(this, void 0, void 0, function* () {
         const { subscription, variables, url } = yield request.json();
         try {
-            const contextValue = yield sofa.contextFactory(serverContext);
             const result = yield subscriptionManager.start({
                 subscription,
                 variables,
                 url,
-            }, contextValue);
+            }, Object.assign(Object.assign({}, serverContext), { request }));
             return new fetch.Response(JSON.stringify(result), {
                 status: 200,
                 statusText: 'OK',
@@ -328,7 +323,8 @@ function createRouter(sofa) {
         const body = yield request.json();
         const variables = body.variables;
         try {
-            const contextValue = yield sofa.contextFactory(serverContext);
+            const sofaServerContext = Object.assign(Object.assign({}, serverContext), { request });
+            const contextValue = yield sofa.contextFactory(sofaServerContext);
             const result = yield subscriptionManager.update({
                 id,
                 variables,
@@ -371,7 +367,7 @@ function createRouter(sofa) {
     return router;
 }
 function createQueryRoute({ sofa, router, fieldName, }) {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e, _f;
     logger.debug(`[Router] Creating ${fieldName} query`);
     const queryType = sofa.schema.getQueryType();
     const operationNode = utils.buildOperationNodeForField({
@@ -405,6 +401,8 @@ function createQueryRoute({ sofa, router, fieldName, }) {
         document: operation,
         path: route.path,
         method: route.method.toUpperCase(),
+        tags: (_e = routeConfig === null || routeConfig === void 0 ? void 0 : routeConfig.tags) !== null && _e !== void 0 ? _e : [],
+        description: (_f = routeConfig === null || routeConfig === void 0 ? void 0 : routeConfig.description) !== null && _f !== void 0 ? _f : '',
     };
 }
 function createMutationRoute({ sofa, router, fieldName, }) {
@@ -438,6 +436,8 @@ function createMutationRoute({ sofa, router, fieldName, }) {
         document: operation,
         path,
         method,
+        tags: (routeConfig === null || routeConfig === void 0 ? void 0 : routeConfig.tags) || [],
+        description: (routeConfig === null || routeConfig === void 0 ? void 0 : routeConfig.description) || '',
     };
 }
 function useHandler(config) {
@@ -469,7 +469,8 @@ function useHandler(config) {
             }
             return Object.assign(Object.assign({}, variables), { [name]: value });
         }, {});
-        const contextValue = yield sofa.contextFactory(serverContext);
+        const sofaServerContext = Object.assign(Object.assign({}, serverContext), { request });
+        const contextValue = yield sofa.contextFactory(sofaServerContext);
         const result = yield sofa.execute({
             schema: sofa.schema,
             document: operation,
@@ -479,8 +480,9 @@ function useHandler(config) {
         });
         if (result.errors) {
             const defaultErrorHandler = (errors) => {
-                return new fetch.Response(errors[0], {
+                return new fetch.Response(JSON.stringify(errors[0]), {
                     status: 500,
+                    headers: { 'Content-Type': 'application/json' },
                 });
             };
             const errorHandler = sofa.errorHandler || defaultErrorHandler;
@@ -619,7 +621,7 @@ function mapToRef(type) {
     return `#/components/schemas/${type}`;
 }
 
-function buildSchemaObjectFromType(type) {
+function buildSchemaObjectFromType(type, opts) {
     const required = [];
     const properties = {};
     const fields = type.getFields();
@@ -628,28 +630,27 @@ function buildSchemaObjectFromType(type) {
         if (graphql.isNonNullType(field.type)) {
             required.push(field.name);
         }
-        properties[fieldName] = resolveField(field);
+        properties[fieldName] = resolveField(field, opts);
         if (field.description) {
             properties[fieldName].description = field.description;
         }
     }
     return Object.assign(Object.assign(Object.assign({ type: 'object' }, (required.length ? { required } : {})), { properties }), (type.description ? { description: type.description } : {}));
 }
-function resolveField(field) {
-    return resolveFieldType(field.type);
+function resolveField(field, opts) {
+    return resolveFieldType(field.type, opts);
 }
 // array -> [type]
 // type -> $ref
 // scalar -> swagger primitive
-function resolveFieldType(type) {
-    var _a, _b;
+function resolveFieldType(type, opts) {
     if (graphql.isNonNullType(type)) {
-        return resolveFieldType(type.ofType);
+        return resolveFieldType(type.ofType, opts);
     }
     if (graphql.isListType(type)) {
         return {
             type: 'array',
-            items: resolveFieldType(type.ofType),
+            items: resolveFieldType(type.ofType, opts),
         };
     }
     if (graphql.isObjectType(type)) {
@@ -658,14 +659,15 @@ function resolveFieldType(type) {
         };
     }
     if (graphql.isScalarType(type)) {
-        return (mapToPrimitive(type.name) || {
+        return (mapToPrimitive(type.name) ||
+            opts.customScalars[type.name] || {
             type: 'object',
         });
     }
     if (graphql.isEnumType(type)) {
         return {
             type: 'string',
-            enum: (_b = (_a = type.astNode) === null || _a === void 0 ? void 0 : _a.values) === null || _b === void 0 ? void 0 : _b.map((value) => value.name.value),
+            enum: type.getValues().map((value) => value.name),
         };
     }
     return {
@@ -673,36 +675,41 @@ function resolveFieldType(type) {
     };
 }
 
-function buildPathFromOperation({ url, schema, operation, useRequestBody, }) {
+function buildPathFromOperation({ url, schema, operation, useRequestBody, tags, description, customScalars, }) {
     const info = getOperationInfo(operation);
-    const description = resolveDescription(schema, info.operation);
-    return Object.assign(Object.assign({ operationId: info.name }, (useRequestBody
+    const summary = resolveSummary(schema, info.operation);
+    return Object.assign(Object.assign({ tags,
+        description,
+        summary, operationId: info.name }, (useRequestBody
         ? {
             requestBody: {
                 content: {
                     'application/json': {
-                        schema: resolveRequestBody(info.operation.variableDefinitions),
+                        schema: resolveRequestBody(info.operation.variableDefinitions, {
+                            customScalars,
+                        }),
                     },
                 },
             },
         }
         : {
-            parameters: resolveParameters(url, info.operation.variableDefinitions),
+            parameters: resolveParameters(url, info.operation.variableDefinitions, { customScalars }),
         })), { responses: {
             200: {
-                description,
+                description: summary,
                 content: {
                     'application/json': {
                         schema: resolveResponse({
                             schema,
                             operation: info.operation,
+                            customScalars,
                         }),
                     },
                 },
             },
         } });
 }
-function resolveParameters(url, variables) {
+function resolveParameters(url, variables, opts) {
     if (!variables) {
         return [];
     }
@@ -711,11 +718,11 @@ function resolveParameters(url, variables) {
             in: isInPath(url, variable.variable.name.value) ? 'path' : 'query',
             name: variable.variable.name.value,
             required: variable.type.kind === graphql.Kind.NON_NULL_TYPE,
-            schema: resolveParamSchema(variable.type),
+            schema: resolveParamSchema(variable.type, opts),
         };
     });
 }
-function resolveRequestBody(variables) {
+function resolveRequestBody(variables, opts) {
     if (!variables) {
         return {};
     }
@@ -725,48 +732,49 @@ function resolveRequestBody(variables) {
         if (variable.type.kind === graphql.Kind.NON_NULL_TYPE) {
             required.push(variable.variable.name.value);
         }
-        properties[variable.variable.name.value] = resolveParamSchema(variable.type);
+        properties[variable.variable.name.value] = resolveParamSchema(variable.type, opts);
     });
     return Object.assign({ type: 'object', properties }, (required.length ? { required } : {}));
 }
 // array -> [type]
 // type -> $ref
 // scalar -> swagger primitive
-function resolveParamSchema(type) {
+function resolveParamSchema(type, opts) {
     if (type.kind === graphql.Kind.NON_NULL_TYPE) {
-        return resolveParamSchema(type.type);
+        return resolveParamSchema(type.type, opts);
     }
     if (type.kind === graphql.Kind.LIST_TYPE) {
         return {
             type: 'array',
-            items: resolveParamSchema(type.type),
+            items: resolveParamSchema(type.type, opts),
         };
     }
     const primitive = mapToPrimitive(type.name.value);
-    return (primitive || {
+    return (primitive ||
+        opts.customScalars[type.name.value] || {
         $ref: mapToRef(type.name.value),
     });
 }
-function resolveResponse({ schema, operation, }) {
+function resolveResponse({ schema, operation, customScalars, }) {
     const operationType = operation.operation;
     const rootField = operation.selectionSet.selections[0];
     if (rootField.kind === graphql.Kind.FIELD) {
         if (operationType === 'query') {
             const queryType = schema.getQueryType();
             const field = queryType.getFields()[rootField.name.value];
-            return resolveFieldType(field.type);
+            return resolveFieldType(field.type, { customScalars });
         }
         if (operationType === 'mutation') {
             const mutationType = schema.getMutationType();
             const field = mutationType.getFields()[rootField.name.value];
-            return resolveFieldType(field.type);
+            return resolveFieldType(field.type, { customScalars });
         }
     }
 }
 function isInPath(url, param) {
     return url.indexOf(`{${param}}`) !== -1;
 }
-function resolveDescription(schema, operation) {
+function resolveSummary(schema, operation) {
     const selection = operation.selectionSet.selections[0];
     const fieldName = selection.name.value;
     const typeDefinition = schema.getType(titleCase.titleCase(operation.operation));
@@ -787,13 +795,13 @@ function isObjectTypeDefinitionNode(node) {
     return node.kind === graphql.Kind.OBJECT_TYPE_DEFINITION;
 }
 
-function OpenAPI({ schema, info, servers, components, security, tags, }) {
+function OpenAPI({ schema, info, servers, components, security, tags, customScalars = {}, }) {
     const types = schema.getTypeMap();
     const swagger = {
         openapi: '3.0.0',
         info,
         servers,
-        tags,
+        tags: [],
         paths: {},
         components: {
             schemas: {},
@@ -803,7 +811,9 @@ function OpenAPI({ schema, info, servers, components, security, tags, }) {
         const type = types[typeName];
         if ((graphql.isObjectType(type) || graphql.isInputObjectType(type)) &&
             !graphql.isIntrospectionType(type)) {
-            swagger.components.schemas[typeName] = buildSchemaObjectFromType(type);
+            swagger.components.schemas[typeName] = buildSchemaObjectFromType(type, {
+                customScalars,
+            });
         }
     }
     if (components) {
@@ -812,6 +822,9 @@ function OpenAPI({ schema, info, servers, components, security, tags, }) {
     if (security) {
         swagger.security = security;
     }
+    if (tags) {
+        swagger.tags = tags;
+    }
     return {
         addRoute(info, config) {
             const basePath = (config === null || config === void 0 ? void 0 : config.basePath) || '';
@@ -820,11 +833,15 @@ function OpenAPI({ schema, info, servers, components, security, tags, }) {
             if (!swagger.paths[path]) {
                 swagger.paths[path] = {};
             }
-            swagger.paths[path][info.method.toLowerCase()] = buildPathFromOperation({
+            const pathsObj = swagger.paths[path];
+            pathsObj[info.method.toLowerCase()] = buildPathFromOperation({
                 url: path,
                 operation: info.document,
                 schema,
                 useRequestBody: ['POST', 'PUT', 'PATCH'].includes(info.method),
+                tags: info.tags || [],
+                description: info.description || '',
+                customScalars,
             });
         },
         get() {

package/index.mjs

@@ -3,8 +3,7 @@ import { getOperationAST, Kind, isScalarType, isEqualType, GraphQLBoolean, isInp
 import { Router } from 'itty-router';
 import { buildOperationNodeForField } from '@graphql-tools/utils';
 import { paramCase } from 'param-case';
-import { v4 } from 'uuid';
-import { fetch, Response } from '@whatwg-node/fetch';
+import { crypto, fetch, Response } from '@whatwg-node/fetch';
 import colors from 'ansi-colors';
 import { createServerAdapter } from '@whatwg-node/server';
 import { titleCase } from 'title-case';
@@ -108,20 +107,17 @@ class SubscriptionManager {
     }
     start(event, contextValue) {
         return __awaiter(this, void 0, void 0, function* () {
-            const id = v4();
+            const id = crypto.randomUUID();
             const name = event.subscription;
             if (!this.operations.has(name)) {
                 throw new Error(`Subscription '${name}' is not available`);
             }
-            const { document, operationName, variables } = this.operations.get(name);
             logger.info(`[Subscription] Start ${id}`, event);
             const result = yield this.execute({
                 id,
                 name,
                 url: event.url,
-                document,
-                operationName,
-                variables,
+                variables: event.variables,
                 contextValue,
             });
             if (typeof result !== 'undefined') {
@@ -160,9 +156,9 @@ class SubscriptionManager {
             }, contextValue);
         });
     }
-    execute({ id, document, name, url, operationName, variables, contextValue, }) {
+    execute({ id, name, url, variables, contextValue, }) {
         return __awaiter(this, void 0, void 0, function* () {
-            const variableNodes = this.operations.get(name).variables;
+            const { document, operationName, variables: variableNodes } = this.operations.get(name);
             const variableValues = variableNodes.reduce((values, variable) => {
                 const value = parseVariable({
                     value: variables[variable.variable.name.value],
@@ -172,7 +168,7 @@ class SubscriptionManager {
                 if (typeof value === 'undefined') {
                     return values;
                 }
-                return Object.assign(Object.assign({}, values), { [name]: value });
+                return Object.assign(Object.assign({}, values), { [variable.variable.name.value]: value });
             }, {});
             const execution = yield this.sofa.subscribe({
                 schema: this.sofa.schema,
@@ -295,12 +291,11 @@ function createRouter(sofa) {
     router.post('/webhook', (request, serverContext) => __awaiter(this, void 0, void 0, function* () {
         const { subscription, variables, url } = yield request.json();
         try {
-            const contextValue = yield sofa.contextFactory(serverContext);
             const result = yield subscriptionManager.start({
                 subscription,
                 variables,
                 url,
-            }, contextValue);
+            }, Object.assign(Object.assign({}, serverContext), { request }));
             return new Response(JSON.stringify(result), {
                 status: 200,
                 statusText: 'OK',
@@ -322,7 +317,8 @@ function createRouter(sofa) {
         const body = yield request.json();
         const variables = body.variables;
         try {
-            const contextValue = yield sofa.contextFactory(serverContext);
+            const sofaServerContext = Object.assign(Object.assign({}, serverContext), { request });
+            const contextValue = yield sofa.contextFactory(sofaServerContext);
             const result = yield subscriptionManager.update({
                 id,
                 variables,
@@ -365,7 +361,7 @@ function createRouter(sofa) {
     return router;
 }
 function createQueryRoute({ sofa, router, fieldName, }) {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e, _f;
     logger.debug(`[Router] Creating ${fieldName} query`);
     const queryType = sofa.schema.getQueryType();
     const operationNode = buildOperationNodeForField({
@@ -399,6 +395,8 @@ function createQueryRoute({ sofa, router, fieldName, }) {
         document: operation,
         path: route.path,
         method: route.method.toUpperCase(),
+        tags: (_e = routeConfig === null || routeConfig === void 0 ? void 0 : routeConfig.tags) !== null && _e !== void 0 ? _e : [],
+        description: (_f = routeConfig === null || routeConfig === void 0 ? void 0 : routeConfig.description) !== null && _f !== void 0 ? _f : '',
     };
 }
 function createMutationRoute({ sofa, router, fieldName, }) {
@@ -432,6 +430,8 @@ function createMutationRoute({ sofa, router, fieldName, }) {
         document: operation,
         path,
         method,
+        tags: (routeConfig === null || routeConfig === void 0 ? void 0 : routeConfig.tags) || [],
+        description: (routeConfig === null || routeConfig === void 0 ? void 0 : routeConfig.description) || '',
     };
 }
 function useHandler(config) {
@@ -463,7 +463,8 @@ function useHandler(config) {
             }
             return Object.assign(Object.assign({}, variables), { [name]: value });
         }, {});
-        const contextValue = yield sofa.contextFactory(serverContext);
+        const sofaServerContext = Object.assign(Object.assign({}, serverContext), { request });
+        const contextValue = yield sofa.contextFactory(sofaServerContext);
         const result = yield sofa.execute({
             schema: sofa.schema,
             document: operation,
@@ -473,8 +474,9 @@ function useHandler(config) {
         });
         if (result.errors) {
             const defaultErrorHandler = (errors) => {
-                return new Response(errors[0], {
+                return new Response(JSON.stringify(errors[0]), {
                     status: 500,
+                    headers: { 'Content-Type': 'application/json' },
                 });
             };
             const errorHandler = sofa.errorHandler || defaultErrorHandler;
@@ -613,7 +615,7 @@ function mapToRef(type) {
     return `#/components/schemas/${type}`;
 }
 
-function buildSchemaObjectFromType(type) {
+function buildSchemaObjectFromType(type, opts) {
     const required = [];
     const properties = {};
     const fields = type.getFields();
@@ -622,28 +624,27 @@ function buildSchemaObjectFromType(type) {
         if (isNonNullType(field.type)) {
             required.push(field.name);
         }
-        properties[fieldName] = resolveField(field);
+        properties[fieldName] = resolveField(field, opts);
         if (field.description) {
             properties[fieldName].description = field.description;
         }
     }
     return Object.assign(Object.assign(Object.assign({ type: 'object' }, (required.length ? { required } : {})), { properties }), (type.description ? { description: type.description } : {}));
 }
-function resolveField(field) {
-    return resolveFieldType(field.type);
+function resolveField(field, opts) {
+    return resolveFieldType(field.type, opts);
 }
 // array -> [type]
 // type -> $ref
 // scalar -> swagger primitive
-function resolveFieldType(type) {
-    var _a, _b;
+function resolveFieldType(type, opts) {
     if (isNonNullType(type)) {
-        return resolveFieldType(type.ofType);
+        return resolveFieldType(type.ofType, opts);
     }
     if (isListType(type)) {
         return {
             type: 'array',
-            items: resolveFieldType(type.ofType),
+            items: resolveFieldType(type.ofType, opts),
         };
     }
     if (isObjectType(type)) {
@@ -652,14 +653,15 @@ function resolveFieldType(type) {
         };
     }
     if (isScalarType(type)) {
-        return (mapToPrimitive(type.name) || {
+        return (mapToPrimitive(type.name) ||
+            opts.customScalars[type.name] || {
             type: 'object',
         });
     }
     if (isEnumType(type)) {
         return {
             type: 'string',
-            enum: (_b = (_a = type.astNode) === null || _a === void 0 ? void 0 : _a.values) === null || _b === void 0 ? void 0 : _b.map((value) => value.name.value),
+            enum: type.getValues().map((value) => value.name),
         };
     }
     return {
@@ -667,36 +669,41 @@ function resolveFieldType(type) {
     };
 }
 
-function buildPathFromOperation({ url, schema, operation, useRequestBody, }) {
+function buildPathFromOperation({ url, schema, operation, useRequestBody, tags, description, customScalars, }) {
     const info = getOperationInfo(operation);
-    const description = resolveDescription(schema, info.operation);
-    return Object.assign(Object.assign({ operationId: info.name }, (useRequestBody
+    const summary = resolveSummary(schema, info.operation);
+    return Object.assign(Object.assign({ tags,
+        description,
+        summary, operationId: info.name }, (useRequestBody
         ? {
             requestBody: {
                 content: {
                     'application/json': {
-                        schema: resolveRequestBody(info.operation.variableDefinitions),
+                        schema: resolveRequestBody(info.operation.variableDefinitions, {
+                            customScalars,
+                        }),
                     },
                 },
             },
         }
         : {
-            parameters: resolveParameters(url, info.operation.variableDefinitions),
+            parameters: resolveParameters(url, info.operation.variableDefinitions, { customScalars }),
         })), { responses: {
             200: {
-                description,
+                description: summary,
                 content: {
                     'application/json': {
                         schema: resolveResponse({
                             schema,
                             operation: info.operation,
+                            customScalars,
                         }),
                     },
                 },
             },
         } });
 }
-function resolveParameters(url, variables) {
+function resolveParameters(url, variables, opts) {
     if (!variables) {
         return [];
     }
@@ -705,11 +712,11 @@ function resolveParameters(url, variables) {
             in: isInPath(url, variable.variable.name.value) ? 'path' : 'query',
             name: variable.variable.name.value,
             required: variable.type.kind === Kind.NON_NULL_TYPE,
-            schema: resolveParamSchema(variable.type),
+            schema: resolveParamSchema(variable.type, opts),
         };
     });
 }
-function resolveRequestBody(variables) {
+function resolveRequestBody(variables, opts) {
     if (!variables) {
         return {};
     }
@@ -719,48 +726,49 @@ function resolveRequestBody(variables) {
         if (variable.type.kind === Kind.NON_NULL_TYPE) {
             required.push(variable.variable.name.value);
         }
-        properties[variable.variable.name.value] = resolveParamSchema(variable.type);
+        properties[variable.variable.name.value] = resolveParamSchema(variable.type, opts);
     });
     return Object.assign({ type: 'object', properties }, (required.length ? { required } : {}));
 }
 // array -> [type]
 // type -> $ref
 // scalar -> swagger primitive
-function resolveParamSchema(type) {
+function resolveParamSchema(type, opts) {
     if (type.kind === Kind.NON_NULL_TYPE) {
-        return resolveParamSchema(type.type);
+        return resolveParamSchema(type.type, opts);
     }
     if (type.kind === Kind.LIST_TYPE) {
         return {
             type: 'array',
-            items: resolveParamSchema(type.type),
+            items: resolveParamSchema(type.type, opts),
         };
     }
     const primitive = mapToPrimitive(type.name.value);
-    return (primitive || {
+    return (primitive ||
+        opts.customScalars[type.name.value] || {
         $ref: mapToRef(type.name.value),
     });
 }
-function resolveResponse({ schema, operation, }) {
+function resolveResponse({ schema, operation, customScalars, }) {
     const operationType = operation.operation;
     const rootField = operation.selectionSet.selections[0];
     if (rootField.kind === Kind.FIELD) {
         if (operationType === 'query') {
             const queryType = schema.getQueryType();
             const field = queryType.getFields()[rootField.name.value];
-            return resolveFieldType(field.type);
+            return resolveFieldType(field.type, { customScalars });
         }
         if (operationType === 'mutation') {
             const mutationType = schema.getMutationType();
             const field = mutationType.getFields()[rootField.name.value];
-            return resolveFieldType(field.type);
+            return resolveFieldType(field.type, { customScalars });
         }
     }
 }
 function isInPath(url, param) {
     return url.indexOf(`{${param}}`) !== -1;
 }
-function resolveDescription(schema, operation) {
+function resolveSummary(schema, operation) {
     const selection = operation.selectionSet.selections[0];
     const fieldName = selection.name.value;
     const typeDefinition = schema.getType(titleCase(operation.operation));
@@ -781,13 +789,13 @@ function isObjectTypeDefinitionNode(node) {
     return node.kind === Kind.OBJECT_TYPE_DEFINITION;
 }
 
-function OpenAPI({ schema, info, servers, components, security, tags, }) {
+function OpenAPI({ schema, info, servers, components, security, tags, customScalars = {}, }) {
     const types = schema.getTypeMap();
     const swagger = {
         openapi: '3.0.0',
         info,
         servers,
-        tags,
+        tags: [],
         paths: {},
         components: {
             schemas: {},
@@ -797,7 +805,9 @@ function OpenAPI({ schema, info, servers, components, security, tags, }) {
         const type = types[typeName];
         if ((isObjectType(type) || isInputObjectType(type)) &&
             !isIntrospectionType(type)) {
-            swagger.components.schemas[typeName] = buildSchemaObjectFromType(type);
+            swagger.components.schemas[typeName] = buildSchemaObjectFromType(type, {
+                customScalars,
+            });
         }
     }
     if (components) {
@@ -806,6 +816,9 @@ function OpenAPI({ schema, info, servers, components, security, tags, }) {
     if (security) {
         swagger.security = security;
     }
+    if (tags) {
+        swagger.tags = tags;
+    }
     return {
         addRoute(info, config) {
             const basePath = (config === null || config === void 0 ? void 0 : config.basePath) || '';
@@ -814,11 +827,15 @@ function OpenAPI({ schema, info, servers, components, security, tags, }) {
             if (!swagger.paths[path]) {
                 swagger.paths[path] = {};
             }
-            swagger.paths[path][info.method.toLowerCase()] = buildPathFromOperation({
+            const pathsObj = swagger.paths[path];
+            pathsObj[info.method.toLowerCase()] = buildPathFromOperation({
                 url: path,
                 operation: info.document,
                 schema,
                 useRequestBody: ['POST', 'PUT', 'PATCH'].includes(info.method),
+                tags: info.tags || [],
+                description: info.description || '',
+                customScalars,
             });
         },
         get() {

package/open-api/index.d.ts

@@ -1,15 +1,26 @@
 import { GraphQLSchema } from 'graphql';
 import { RouteInfo } from '../types';
-export declare function OpenAPI({ schema, info, servers, components, security, tags, }: {
+import { OpenAPIV3 } from 'openapi-types';
+export declare function OpenAPI({ schema, info, servers, components, security, tags, customScalars, }: {
     schema: GraphQLSchema;
-    info: Record<string, any>;
-    servers?: Record<string, any>[];
+    info: OpenAPIV3.InfoObject;
+    servers?: OpenAPIV3.ServerObject[];
     components?: Record<string, any>;
-    security?: Record<string, any>[];
-    tags?: Record<string, any>[];
+    security?: OpenAPIV3.SecurityRequirementObject[];
+    tags?: OpenAPIV3.TagObject[];
+    /**
+     * Override mapping of custom scalars to OpenAPI
+     * @example
+     * ```js
+     * {
+     *   Date: { type: "string",  format: "date" }
+     * }
+     * ```
+     */
+    customScalars?: Record<string, any>;
 }): {
     addRoute(info: RouteInfo, config?: {
         basePath?: string;
     }): void;
-    get(): any;
+    get(): OpenAPIV3.Document<{}>;
 };

package/open-api/operations.d.ts

@@ -1,7 +1,11 @@
 import { DocumentNode, GraphQLSchema } from 'graphql';
-export declare function buildPathFromOperation({ url, schema, operation, useRequestBody, }: {
+import { OpenAPIV3 } from 'openapi-types';
+export declare function buildPathFromOperation({ url, schema, operation, useRequestBody, tags, description, customScalars, }: {
     url: string;
     schema: GraphQLSchema;
     operation: DocumentNode;
     useRequestBody: boolean;
-}): any;
+    tags?: string[];
+    description?: string;
+    customScalars: Record<string, any>;
+}): OpenAPIV3.OperationObject;

package/open-api/types.d.ts

@@ -1,3 +1,7 @@
 import { GraphQLObjectType, GraphQLInputObjectType, GraphQLType } from 'graphql';
-export declare function buildSchemaObjectFromType(type: GraphQLObjectType | GraphQLInputObjectType): any;
-export declare function resolveFieldType(type: GraphQLType): any;
+export declare function buildSchemaObjectFromType(type: GraphQLObjectType | GraphQLInputObjectType, opts: {
+    customScalars: Record<string, any>;
+}): any;
+export declare function resolveFieldType(type: GraphQLType, opts: {
+    customScalars: Record<string, any>;
+}): any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sofa-api",
-  "version": "0.12.0-alpha.0",
+  "version": "0.13.0",
   "description": "Create REST APIs with GraphQL",
   "sideEffects": false,
   "peerDependencies": {
@@ -12,10 +12,10 @@
     "@whatwg-node/server": "^0.4.1",
     "ansi-colors": "4.1.3",
     "itty-router": "^2.6.1",
+    "openapi-types": "12.0.2",
     "param-case": "3.0.4",
     "title-case": "3.0.3",
-    "tslib": "2.4.0",
-    "uuid": "8.3.2"
+    "tslib": "2.4.0"
   },
   "repository": {
     "type": "git",
@@ -50,4 +50,4 @@
     },
     "./package.json": "./package.json"
   }
-}
+}

package/sofa.d.ts

@@ -5,6 +5,8 @@ interface RouteConfig {
     method?: Method;
     path?: string;
     responseStatus?: number;
+    tags?: string[];
+    description?: string;
 }
 export interface Route {
     method: Method;

package/types.d.ts

@@ -1,3 +1,4 @@
+import { DefaultServerAdapterContext } from '@whatwg-node/server';
 import { DocumentNode } from 'graphql';
 export declare type ContextValue = Record<string, any>;
 export declare type Ignore = string[];
@@ -6,9 +7,11 @@ export interface RouteInfo {
     document: DocumentNode;
     path: string;
     method: Method;
+    tags?: string[];
+    description?: string;
 }
 export declare type OnRoute = (info: RouteInfo) => void;
-export declare type ContextFn = (init: {
-    req: any;
-    res: any;
-}) => Promise<ContextValue> | ContextValue;
+export declare type ContextFn = (serverContext: DefaultSofaServerContext) => Promise<ContextValue> | ContextValue;
+export declare type DefaultSofaServerContext = DefaultServerAdapterContext & {
+    request: Request;
+};

package/open-api/interfaces.d.ts

@@ -1,325 +0,0 @@
-declare type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
-export declare namespace OpenAPI {
-    export interface Contact {
-        /**
-         * The identifying name of the contact person/organization.
-         */
-        name?: string;
-        /**
-         * The URL pointing to the contact information. MUST be in the format of a URL.
-         */
-        url?: string;
-        /**
-         * The email address of the contact person/organization. MUST be in the format of an email address.
-         */
-        email?: string;
-    }
-    export interface License {
-        /**
-         * The license name used for the API.
-         */
-        name: string;
-        /**
-         * A URL to the license used for the API. MUST be in the format of a URL.
-         */
-        url?: string;
-    }
-    export interface Info {
-        /**
-         * The title of the application.
-         */
-        title: string;
-        /**
-         * A short description of the application. CommonMark syntax MAY be used for rich text representation.
-         */
-        description?: string;
-        /**
-         * A URL to the Terms of Service for the API. MUST be in the format of a URL.
-         */
-        termsOfService?: string;
-        /**
-         * The contact information for the exposed API.
-         */
-        contact?: Contact;
-        /**
-         * The license information for the exposed API.
-         */
-        license?: License;
-        /**
-         * The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).
-         */
-        version: string;
-    }
-    export interface Reference {
-        /**
-         * The reference string.
-         */
-        $ref: string;
-    }
-    export interface Parameter {
-        /**
-         * The name of the parameter. Parameter names are case sensitive.
-         * - If in is "path", the name field MUST correspond to the associated path segment from the path field in the Paths Object. See Path Templating for further information.
-         * - If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored.
-         * - For all other cases, the name corresponds to the parameter name used by the in property
-         */
-        name: string;
-        /**
-         * The location of the parameter. Possible values are "query", "header", "path" or "cookie".
-         */
-        in: 'query' | 'header' | 'path' | 'cookie';
-        /**
-         * A brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
-         */
-        description?: string;
-        /**
-         * Determines whether this parameter is mandatory. If the parameter location is "path", this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be included and its default value is false.
-         */
-        required: boolean;
-        /**
-         * Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is false.
-         */
-        deprecated?: boolean;
-        /**
-         * Sets the ability to pass empty-valued parameters. This is valid only for query parameters and allows sending a parameter with an empty value. Default value is false. If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.
-         */
-        allowEmptyValue?: boolean;
-        schema?: Reference | Schema;
-    }
-    export interface RequestBody {
-        /**
-         * A brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
-         */
-        description?: string;
-        /**
-         * The content of the request body. The key is a media type or media type range and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
-         */
-        content: Array<string>;
-        /**
-         * Determines if the request body is required in the request. Defaults to false.
-         */
-        required?: boolean;
-    }
-    export type Header = Omit<Parameter, 'name' | 'in'>;
-    export interface Link {
-        /**
-         * A relative or absolute reference to an OAS operation. This field is mutually exclusive of the operationId field, and MUST point to an Operation Object. Relative operationRef values MAY be used to locate an existing Operation Object in the OpenAPI definition.
-         */
-        operationRef?: string;
-        /**
-         * The name of an existing, resolvable OAS operation, as defined with a unique operationId. This field is mutually exclusive of the operationRef field.
-         */
-        operationId?: string;
-        /**
-         * A map representing parameters to pass to an operation as specified with operationId or identified via operationRef. The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and passed to the linked operation. The parameter name can be qualified using the parameter location [{in}.]{name} for operations that use the same parameter name in different locations (e.g. path.id).
-         */
-        parameters?: Record<string, any>;
-        /**
-         * A literal value or {expression} to use as a request body when calling the target operation.
-         */
-        requestBody?: any;
-        /**
-         * A description of the link. CommonMark syntax MAY be used for rich text representation.
-         */
-        description?: string;
-    }
-    interface Response {
-        /**
-         * A short description of the response. CommonMark syntax MAY be used for rich text representation.
-         */
-        description: string;
-        headers?: {
-            [header: string]: Header | Reference;
-        };
-        links?: {
-            [link: string]: Link | Reference;
-        };
-    }
-    interface Responses {
-        default: Response | Reference;
-        [httpStatusCode: number]: Response | Reference;
-    }
-    export interface Operation {
-        /**
-         * A list of tags for API documentation control.
-         * Tags can be used for logical grouping of operations by resources or any other qualifier.
-         */
-        tags?: string[];
-        /**
-         * A short summary of what the operation does.
-         */
-        summary?: string;
-        /**
-         * A verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
-         */
-        description?: string;
-        /**
-         * Additional external documentation for this operation.
-         */
-        externalDocs?: {
-            /**
-             * The URL for the target documentation. Value MUST be in the format of a URL.
-             */
-            url: string;
-            /**
-             * A short description of the target documentation. CommonMark syntax MAY be used for rich text representation.
-             */
-            description?: string;
-        };
-        /**
-         * Unique string used to identify the operation.
-         * The id MUST be unique among all operations described in the API.
-         * The operationId value is case-sensitive.
-         * Tools and libraries MAY use the operationId to uniquely identify an operation,
-         * therefore, it is RECOMMENDED to follow common programming naming conventions.
-         */
-        operationId?: string;
-        /**
-         * A list of parameters that are applicable for this operation.
-         * If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
-         * The list MUST NOT include duplicated parameters.
-         * A unique parameter is defined by a combination of a name and location.
-         * The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters.
-         */
-        parameters?: Array<Parameter | Reference>;
-        /**
-         * The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
-         */
-        requestBody?: RequestBody | Reference;
-        /**
-         * The list of possible responses as they are returned from executing this operation.
-         */
-        responses?: Responses;
-        /**
-         * Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is false.
-         */
-        deprecated?: boolean;
-    }
-    export interface PathItem {
-        /**
-         * Allows for an external definition of this path item.
-         * The referenced structure MUST be in the format of a Path Item Object.
-         * If there are conflicts between the referenced definition and this Path Item's definition, the behavior is undefined.
-         */
-        $ref?: string;
-        /**
-         * An optional, string summary, intended to apply to all operations in this path.
-         */
-        summary?: string;
-        /**
-         * An optional, string description, intended to apply to all operations in this path.
-         * CommonMark syntax MAY be used for rich text representation.
-         */
-        description?: string;
-        /**
-         * A definition of a GET operation on this path.
-         */
-        get?: Operation;
-        /**
-         * A definition of a PUT operation on this path.
-         */
-        put?: Operation;
-        /**
-         * A definition of a POST operation on this path.
-         */
-        post?: Operation;
-        /**
-         * A definition of a DELETE operation on this path.
-         */
-        delete?: Operation;
-        /**
-         * A definition of a OPTIONS operation on this path.
-         */
-        options?: Operation;
-        /**
-         * A definition of a HEAD operation on this path.
-         */
-        head?: Operation;
-        /**
-         * A definition of a PATCH operation on this path.
-         */
-        patch?: Operation;
-        /**
-         * A definition of a TRACE operation on this path.
-         */
-        trace?: Operation;
-        /**
-         * A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location. The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters.
-         */
-        parameters?: Array<Parameter | Reference>;
-    }
-    export interface XML {
-        /**
-         * 	Replaces the name of the element/attribute used for the described schema property. When defined within items, it will affect the name of the individual XML elements within the list. When defined alongside type being array (outside the items), it will affect the wrapping element and only if wrapped is true. If wrapped is false, it will be ignored.
-         */
-        name?: string;
-        /**
-         * The URI of the namespace definition. Value MUST be in the form of an absolute URI.
-         */
-        namespace?: string;
-        /**
-         * The prefix to be used for the name.
-         */
-        prefix?: string;
-        /**
-         * Declares whether the property definition translates to an attribute instead of an element. Default value is false.
-         */
-        attribute?: boolean;
-        /**
-         * MAY be used only for an array definition. Signifies whether the array is wrapped (for example, <books><book/><book/></books>) or unwrapped (<book/><book/>). Default value is false. The definition takes effect only when defined alongside type being array (outside the items).
-         */
-        wrapped?: boolean;
-    }
-    export interface Schema {
-        /**
-         * Allows sending a null value for the defined schema. Default value is false.
-         */
-        nullable?: boolean;
-        /**
-         * Relevant only for Schema "properties" definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as readOnly being true and is in the required list, the required will take effect on the response only. A property MUST NOT be marked as both readOnly and writeOnly being true. Default value is false.
-         */
-        readOnly?: boolean;
-        /**
-         * Relevant only for Schema "properties" definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as writeOnly being true and is in the required list, the required will take effect on the request only. A property MUST NOT be marked as both readOnly and writeOnly being true. Default value is false.
-         */
-        writeOnly?: boolean;
-        /**
-         * This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property.
-         */
-        xml?: XML;
-        /**
-         * Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is false.
-         */
-        deprecated?: boolean;
-    }
-    export interface Components {
-        /**
-         * An object to hold reusable Schema Objects.
-         */
-        schemas?: Record<string, Schema | Reference>;
-    }
-    export interface OpenAPI {
-        /**
-         * This string MUST be the semantic version number of the OpenAPI Specification version that the OpenAPI document uses.
-         * The openapi field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document.
-         * This is not related to the API info.version string.
-         */
-        openapi: string;
-        /**
-         * Provides metadata about the API. The metadata MAY be used by tooling as required.
-         */
-        info: Info;
-        /**
-         * The available paths and operations for the API.
-         */
-        paths: {
-            [path: string]: PathItem;
-        };
-        /**
-         * An element to hold various schemas for the specification.
-         */
-        components?: Components;
-    }
-    export {};
-}
-export {};