@sleeksky/alt-swagger 2.5.0 → 3.0.0

package/README.md

@@ -1,24 +1,515 @@
-# Spec API
+# Alt Swagger
 
-Quickly spec your APIs for Swagger / OpenAPI interface. Uses @sleeksky/alt-schema for specifying JSON schema.
+A fluent, programmatic API for generating OpenAPI 3.0 specifications. Quickly define your REST API endpoints with request/response schemas, parameters, security, and more using a simple, chainable syntax.
 
-# Example
-```JavaScript
-let refRequest = docs.ref.schema('example','{id:i:1,name:s:foo,label:{id:i:2,name:?s:bar},arr:[{a:b:false}]}');
+Built on top of [@sleeksky/alt-schema](https://github.com/sleeksky-dev/alt-schema) for intuitive JSON schema definitions.
 
-docs.put('/:id').tag("dot-notation").req(refRequest).res(200, '{hello,world}');
+## Features
+
+- 🚀 **Fluent API**: Chain methods to define endpoints declaratively
+- 📝 **Schema-first**: Define request/response schemas using simple string syntax
+- 🔒 **Security**: Built-in support for authentication schemes
+- 🏷️ **Rich Metadata**: Tags, summaries, descriptions, deprecation
+- 🔄 **Reusable Schemas**: Define and reference schemas across endpoints
+- 🎯 **TypeScript Support**: Full TypeScript definitions included
+- 📊 **OpenAPI 3.0**: Generates valid OpenAPI 3.0 specifications
+
+## Installation
+
+```bash
+npm install @sleeksky/alt-swagger
+# or
+yarn add @sleeksky/alt-swagger
+# or
+pnpm add @sleeksky/alt-swagger
+```
+
+## Quick Start
+
+```javascript
+const swagger = require('@sleeksky/alt-swagger');
+
+// Define your API
+swagger.server('https://api.example.com', 'Production API');
+
+// Define endpoints
+swagger.get('/users')
+  .summary('Get users')
+  .query('limit:i:10,offset:i:0')
+  .res(200, '[{id:i,name:s,email:s}]');
+
+swagger.post('/users')
+  .summary('Create user')
+  .req('{name:s,email:s}')
+  .res(201, '{id:i,name:s,email:s}')
+  .res(400, '{error:s}');
+
+// Generate OpenAPI spec
+const spec = swagger.swaggerDoc('User API', '1.0.0');
+console.log(JSON.stringify(spec, null, 2));
+```
+
+## Schema Syntax
+
+Alt Swagger uses a compact string syntax for defining JSON schemas, powered by alt-schema:
+
+### Basic Types
+- `s` - string
+- `i` - integer
+- `n` - number
+- `b` - boolean
+- `o` - object
+- `a` - array
+
+### Examples
+
+```javascript
+// Simple object
+'{name:s, age:i}'
+
+// With default values
+'{name:s:John, age:i:25}'
+
+// Optional fields (prefixed with ?)
+'{name:s, age:?i, email:?s}'
+
+// Nested objects
+'{user:{name:s, age:i}, active:b}'
+
+// Arrays
+'[{id:i, name:s}]'
+
+// Complex nested structure
+'{id:i, profile:{name:s, settings:{theme:s:dark, notifications:b:true}}}'
+```
+
+## API Reference
+
+### Core Methods
+
+#### `swagger.server(url, description?)`
+Define API servers.
+
+```javascript
+swagger.server('https://api.example.com', 'Production');
+swagger.server('https://staging.api.example.com', 'Staging');
+```
+
+#### `swagger.tag(name, description?)`
+Define tags for grouping endpoints.
+
+```javascript
+swagger.tag('Users', 'User management endpoints');
+swagger.tag('Posts', 'Blog post endpoints');
+```
+
+### HTTP Methods
+
+All HTTP methods return a fluent API for chaining:
+
+#### `swagger.get(path)`
+#### `swagger.post(path)`
+#### `swagger.put(path)`
+#### `swagger.patch(path)`
+#### `swagger.del(path)` (or `swagger.delete(path)`)
+
+```javascript
+swagger.get('/users/{id}')
+  .summary('Get user by ID')
+  .res(200, '{id:i, name:s, email:s}')
+  .res(404, '{error:s}');
+```
+
+### Path Parameters
+
+Parameters in curly braces are automatically detected:
+
+```javascript
+// /users/{id} automatically creates path parameter 'id'
+swagger.get('/users/{id}')
+  .res(200, '{id:i, name:s}');
+
+// With default values
+swagger.get('/users/{id:123}')
+  .res(200, '{id:i, name:s}');
+```
+
+### Fluent API Methods
+
+#### `.req(schema)`
+Define request body schema.
+
+```javascript
+swagger.post('/users')
+  .req('{name:s, email:s, age:?i}')
+  .res(201, '{id:i, name:s, email:s}');
+```
+
+#### `.res(statusCode, schema)`
+Define response schema for a status code.
+
+```javascript
+swagger.get('/users')
+  .res(200, '[{id:i, name:s}]')
+  .res(404, '{error:s}')
+  .res(500, '{error:s, code:i}');
+```
+
+#### `.query(params)`
+Add query parameters. Accepts string or array.
+
+```javascript
+// Single parameter
+swagger.get('/users').query('limit:i:10');
+
+// Multiple parameters (comma-separated)
+swagger.get('/users').query('limit:i:10,offset:i:0');
+
+// Array format
+swagger.get('/users').query(['limit:i:10', 'offset:i:0']);
+
+// Optional parameters
+swagger.get('/users').query('search:?s');
+```
+
+#### `.header(params)`
+Add header parameters.
+
+```javascript
+swagger.get('/users')
+  .header('authorization')
+  .header('x-api-key:?');
+```
+
+#### `.tag(name)`
+Add tags to the endpoint.
+
+```javascript
+swagger.get('/users')
+  .tag('Users')
+  .tag('Public');
+```
+
+#### `.summary(text)`
+Add summary to the endpoint.
+
+```javascript
+swagger.get('/users')
+  .summary('Retrieve a list of users');
+```
+
+#### `.desc(text)` or `.description(text)`
+Add description to the endpoint.
+
+```javascript
+swagger.get('/users')
+  .desc('Returns a paginated list of users with optional filtering');
+```
+
+#### `.security(name)`
+Apply security scheme to the endpoint.
+
+```javascript
+swagger.get('/users')
+  .security('bearerAuth');
+```
+
+#### `.deprecate()`
+Mark endpoint as deprecated.
+
+```javascript
+swagger.get('/old-endpoint')
+  .deprecate()
+  .res(200, '{message:s}');
+```
+
+### Schema Management
+
+#### `swagger.ref.schema(name, schema)`
+Define reusable schemas.
+
+```javascript
+const userSchema = swagger.ref.schema('User', '{id:i, name:s, email:s}');
+const errorSchema = swagger.ref.schema('Error', '{error:s, code:i}');
+
+swagger.get('/users')
+  .res(200, userSchema)
+  .res(500, errorSchema);
+```
+
+### Security
+
+#### `swagger.security(name, options?)`
+Define security schemes.
+
+```javascript
+// Bearer token
+swagger.security('bearerAuth');
+
+// API Key
+swagger.security('apiKey', {
+  type: 'apiKey',
+  in: 'header',
+  name: 'X-API-Key'
+});
+
+// Basic auth
+swagger.security('basicAuth', {
+  type: 'http',
+  scheme: 'basic'
+});
+```
+
+### Document Generation
+
+#### `swagger.swaggerDoc(title?, version?)`
+Generate the complete OpenAPI specification.
+
+```javascript
+const spec = swagger.swaggerDoc('My API', '1.0.0');
+// Returns OpenAPI 3.0 compliant object
+```
+
+### Utility Methods
+
+#### `swagger.reset()`
+Clear all defined specifications.
+
+```javascript
+swagger.reset(); // Start fresh
+```
+
+#### `swagger.remove(options)`
+Remove endpoints.
+
+```javascript
+// Remove specific path
+swagger.remove({ path: '/users' });
+
+// Remove by tag
+swagger.remove({ tag: 'Deprecated' });
+```
+
+## Complete Examples
+
+### Basic CRUD API
+
+```javascript
+const swagger = require('@sleeksky/alt-swagger');
+
+swagger.server('https://api.example.com', 'User Management API');
+swagger.tag('Users', 'User operations');
+
+// Define schemas
+const userSchema = swagger.ref.schema('User', '{id:i, name:s, email:s, created_at:s}');
+const createUserSchema = swagger.ref.schema('CreateUser', '{name:s, email:s}');
+const errorSchema = swagger.ref.schema('Error', '{error:s, code:i}');
+
+// Security
+swagger.security('bearerAuth');
+
+// Endpoints
+swagger.get('/users')
+  .tag('Users')
+  .summary('List users')
+  .security('bearerAuth')
+  .query('limit:?i:10,offset:?i:0')
+  .res(200, `[${userSchema}]`)
+  .res(401, errorSchema);
+
+swagger.post('/users')
+  .tag('Users')
+  .summary('Create user')
+  .req(createUserSchema)
+  .res(201, userSchema)
+  .res(400, errorSchema);
+
+swagger.get('/users/{id}')
+  .tag('Users')
+  .summary('Get user by ID')
+  .security('bearerAuth')
+  .res(200, userSchema)
+  .res(404, errorSchema);
+
+swagger.put('/users/{id}')
+  .tag('Users')
+  .summary('Update user')
+  .security('bearerAuth')
+  .req(createUserSchema)
+  .res(200, userSchema)
+  .res(400, errorSchema)
+  .res(404, errorSchema);
+
+swagger.del('/users/{id}')
+  .tag('Users')
+  .summary('Delete user')
+  .security('bearerAuth')
+  .res(204)
+  .res(404, errorSchema);
+
+const spec = swagger.swaggerDoc('User API', '1.0.0');
+```
+
+### Express Integration
+
+```javascript
+const express = require('express');
+const swaggerUi = require('swagger-ui-express');
+const swagger = require('@sleeksky/alt-swagger');
+
+const app = express();
+
+// Define API spec
+swagger.server('http://localhost:3000', 'Local API');
+
+swagger.get('/health')
+  .summary('Health check')
+  .res(200, '{status:s, timestamp:s}');
+
+swagger.get('/users/{id}')
+  .summary('Get user')
+  .res(200, '{id:i, name:s}');
+
+// Serve Swagger UI
+app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swagger.swaggerDoc('My API')));
+
+// API routes
+app.get('/health', (req, res) => {
+  res.json({ status: 'ok', timestamp: new Date().toISOString() });
+});
+
+app.get('/users/:id', (req, res) => {
+  const user = { id: parseInt(req.params.id), name: 'John Doe' };
+  res.json(user);
+});
+
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+  console.log('API docs at http://localhost:3000/api-docs');
+});
+```
+
+### Advanced Schema Examples
+
+```javascript
+const swagger = require('@sleeksky/alt-swagger');
+
+// Complex nested schemas
+const profileSchema = swagger.ref.schema('Profile', `
+  {
+    personal: {
+      firstName: s,
+      lastName: s,
+      age: ?i,
+      email: s
+    },
+    preferences: {
+      theme: s:light,
+      notifications: {
+        email: b:true,
+        push: b:false
+      }
+    },
+    tags: [s]
+  }
+`);
+
+// Array responses
+swagger.get('/posts')
+  .summary('Get blog posts')
+  .query('category:?s,tag:?s,published:?b:true')
+  .res(200, `
+    [{
+      id: i,
+      title: s,
+      content: s,
+      author: {id:i, name:s},
+      tags: [s],
+      published: b,
+      created_at: s
+    }]
+  `);
+
+// Union-like responses (use oneOf in OpenAPI)
+swagger.post('/upload')
+  .summary('Upload file')
+  .req('{file:s, type:s}')  // In practice, use multipart/form-data
+  .res(200, '{id:s, url:s, size:i}')
+  .res(400, '{error:s, code:s}');
+```
+
+## TypeScript Support
+
+Alt Swagger includes full TypeScript definitions:
+
+```typescript
+import * as swagger from '@sleeksky/alt-swagger';
+
+swagger.server('https://api.example.com');
+swagger.get('/users').res(200, '[{id:number, name:string}]');
+
+const spec: swagger.SwaggerDoc = swagger.swaggerDoc('API');
+```
+
+## Integration with Frameworks
+
+### Fastify
+
+```javascript
+const fastify = require('fastify')();
+const swagger = require('@sleeksky/alt-swagger');
+
+// Define spec
+swagger.server('http://localhost:3000');
+swagger.get('/users').res(200, '[{id:i, name:s}]');
+
+// Register Swagger
+fastify.register(require('@fastify/swagger'), {
+  specification: {
+    document: swagger.swaggerDoc('Fastify API')
+  }
+});
+```
+
+### Hapi
+
+```javascript
+const Hapi = require('@hapi/hapi');
+const swagger = require('@sleeksky/alt-swagger');
+
+const server = Hapi.server({ port: 3000 });
+
+// Define spec
+swagger.server('http://localhost:3000');
+swagger.get('/users').res(200, '[{id:i, name:s}]');
+
+// Use hapi-swagger
+server.register([
+  require('hapi-swagger'),
+  {
+    options: {
+      documentationPage: true,
+      swaggerOptions: {
+        spec: swagger.swaggerDoc('Hapi API')
+      }
+    }
+  }
+]);
 ```
-![](https://i.ibb.co/ypWxGZJ/spec-api-ss1.png)
-# Installation
 
-npm install -s @sleeksky/alt-swagger
+## Best Practices
 
-const docs = require('@sleeksky/alt-swagger');
+1. **Define schemas first**: Use `swagger.ref.schema()` for reusable schemas
+2. **Use meaningful tags**: Group related endpoints with tags
+3. **Document thoroughly**: Always include summaries and descriptions
+4. **Handle errors**: Define error responses for all endpoints
+5. **Version your API**: Use semantic versioning in `swaggerDoc()`
+6. **Validate schemas**: Test your generated specs with OpenAPI validators
 
-# Usage
+## Contributing
 
-See example.js
+Contributions are welcome! Please feel free to submit issues and pull requests.
 
-# License
+## License
 
-MIT © SleekSky
+MIT © [SleekSky](https://sleeksky.com)

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@sleeksky/alt-swagger",
-  "version": "2.5.0",
-  "description": "Quickly spec your APIs for Swagger / OpenAPI interface",
-  "main": "./src/index.js",
+  "version": "3.0.0",
+  "description": "A fluent, programmatic API for generating OpenAPI 3.0 specifications with TypeScript support. Define REST API endpoints, schemas, parameters, and security using a simple, chainable syntax.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "scripts": {
-    "test": "mocha",
+    "build": "tsc",
+    "test": "mocha --require ts-node/register test/index.ts",
     "cover": "nyc --check-coverage npm run test",
-    "prepublish": "npm run test"
+    "prepublish": "npm run build && npm run test"
   },
   "files": [
     "src"
@@ -29,12 +31,19 @@
   },
   "homepage": "https://github.com/sleeksky-dev/alt-swagger#readme",
   "devDependencies": {
+    "@types/chai": "^5.2.3",
+    "@types/express": "^5.0.6",
+    "@types/lodash": "^4.17.21",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^25.0.3",
     "chai": "^4.1.2",
     "cross-env": "^5.1.3",
     "express": "^4.17.1",
     "mocha": "^6.1.3",
     "nyc": "^13.3.0",
-    "swagger-ui-express": "^4.1.6"
+    "swagger-ui-express": "^4.1.6",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
   },
   "dependencies": {
     "@sleeksky/alt-schema": "^2.1.0",

package/src/index.ts

@@ -0,0 +1,274 @@
+/**
+  Author: Yusuf Bhabhrawala
+ */
+import "./utils";
+import * as _ from "lodash";
+import { toSwaggerSchema, pathParameters, pathClean, toParameter, SwaggerSchema, PathParameter, Parameter } from "./utils";
+
+interface Server {
+  url: string;
+  description?: string;
+}
+
+interface Tag {
+  name: string;
+  description?: string;
+}
+
+interface SecurityScheme {
+  type: string;
+  scheme?: string;
+  bearerFormat?: string | null;
+  in?: string;
+  required?: boolean;
+}
+
+interface Components {
+  securitySchemes?: { [key: string]: SecurityScheme };
+  schemas?: { [key: string]: SwaggerSchema };
+  [key: string]: any;
+}
+
+interface ResponseSpec {
+  content?: { [key: string]: { schema: SwaggerSchema } };
+  description: string;
+}
+
+interface PathSpec {
+  parameters: (PathParameter | Parameter)[];
+  responses: { [key: string]: ResponseSpec };
+  description: string;
+  tags?: string[];
+  summary?: string;
+  security?: { [key: string]: string[] }[];
+  deprecated?: boolean;
+  requestBody?: {
+    content: { [key: string]: { schema: SwaggerSchema } };
+  };
+}
+
+interface Paths {
+  [key: string]: {
+    [method: string]: PathSpec;
+  };
+}
+
+const paths: Paths = {};
+const components: Components = {};
+const tags: Tag[] = [];
+const servers: Server[] = [];
+
+function reset(): void {
+  Object.keys(paths).forEach((key) => delete paths[key]);
+  Object.keys(components).forEach((key) => delete components[key]);
+  tags.splice(0, tags.length);
+  servers.splice(0, servers.length);
+}
+
+function server(url: string, description?: string): void {
+  servers.push({ url, description });
+}
+
+interface ApiOptions {
+  path: string;
+  method: string;
+  tag?: string;
+  desc?: string;
+  summary?: string;
+  req?: string;
+  header?: string | string[];
+  query?: string | string[];
+  security?: string;
+  deprecated?: boolean;
+  [key: string]: any; // for numeric response codes
+}
+
+interface ApiExtension {
+  req: (flatSch: string) => ApiExtension;
+  res: (code: string | number, flatSch: string) => ApiExtension;
+  query: (strArr: string | string[]) => ApiExtension;
+  header: (strArr: string | string[]) => ApiExtension;
+  tag: (str: string) => ApiExtension;
+  summary: (str: string) => ApiExtension;
+  desc: (str: string) => ApiExtension;
+  security: (str: string) => ApiExtension;
+  deprecate: () => ApiExtension;
+  remove: () => void;
+}
+
+function api(opt: ApiOptions): ApiExtension {
+  let path = `${pathClean(opt.path)}.${opt.method}`;
+  let spec: PathSpec = _.get(paths as any, path, null) as PathSpec;
+  if (!spec) {
+    spec = { parameters: [], responses: {}, description: "" };
+    const pathParams = pathParameters(opt.path);
+    if (pathParams.length > 0) spec.parameters = pathParams;
+    _.set(paths, path, spec);
+  }
+
+  let ext: ApiExtension = {} as ApiExtension;
+
+  const req = (flatSch: string): ApiExtension => {
+    let schema = flatSch.match(/^#/) ? { $ref: flatSch } : toSwaggerSchema(flatSch);
+    spec.requestBody = {
+      content: { "application/json": { schema } },
+    };
+    return ext;
+  };
+  const res = (code: string | number, flatSch: string): ApiExtension => {
+    let schema = flatSch.match(/^#/) ? { $ref: flatSch } : toSwaggerSchema(flatSch);
+    spec.responses[code] = {
+      content: { [schema.type === "string" ? "text/plain" : "application/json"]: { schema } },
+      description: "",
+    };
+    return ext;
+  };
+  const query = (strArr: string | string[]): ApiExtension => {
+    if (!_.isArray(strArr)) strArr = (strArr as string).split(",");
+    strArr.forEach((str) => {
+      spec.parameters.push(toParameter('query', str));
+    });
+    return ext;
+  };
+  const header = (strArr: string | string[]): ApiExtension => {
+    if (!_.isArray(strArr)) strArr = (strArr as string).split(",");
+    strArr.forEach((str) => {
+      spec.parameters.push(toParameter('header', str));
+    });
+    return ext;
+  };
+  const tag = (str: string): ApiExtension => { spec.tags = [str]; return ext; };
+  const summary = (str: string): ApiExtension => { spec.summary = str; return ext; };
+  const desc = (str: string): ApiExtension => { spec.description = str; return ext; };
+  const security = (str: string): ApiExtension => { spec.security = [ { [str]: []}]; return ext; }
+  const deprecate = (): ApiExtension => { spec.deprecated = true; return ext; };
+  const remove = (): void => { _.unset(paths, `${pathClean(opt.path)}.${opt.method}`); };
+
+  Object.assign(ext, { req, res, query, header, tag, summary, desc, deprecate, remove, security });
+
+  // support all ext in parameters
+  Object.keys(ext).forEach(k => {
+    if (opt[k]) (ext as any)[k](opt[k]);
+  });
+  Object.keys(opt).filter(k => k.match(/^[0-9]+$/)).forEach(k => ext.res(parseInt(k), opt[k]));
+
+  return ext;
+}
+
+function get(path: string = "", opt: Partial<ApiOptions> = {}): ApiExtension {
+  opt.method = "get";
+  opt.path = path;
+  return api(opt as ApiOptions);
+}
+
+function post(path: string = "", opt: Partial<ApiOptions> = {}): ApiExtension {
+  opt.method = "post";
+  opt.path = path;
+  return api(opt as ApiOptions);
+}
+
+function put(path: string = "", opt: Partial<ApiOptions> = {}): ApiExtension {
+  opt.method = "put";
+  opt.path = path;
+  return api(opt as ApiOptions);
+}
+
+function patch(path: string = "", opt: Partial<ApiOptions> = {}): ApiExtension {
+  opt.method = "patch";
+  opt.path = path;
+  return api(opt as ApiOptions);
+}
+
+function del(path: string = "", opt: Partial<ApiOptions> = {}): ApiExtension {
+  opt.method = "delete";
+  opt.path = path;
+  return api(opt as ApiOptions);
+}
+
+interface RemoveOptions {
+  path?: string;
+  tag?: string;
+}
+
+function remove({path, tag}: RemoveOptions): void {
+  if (path) _.unset(paths, `${pathClean(path)}`);
+  if (tag) {
+    Object.keys(paths).forEach(p => {
+      Object.keys(paths[p]).forEach(method => {
+        if (paths[p][method].tags && paths[p][method].tags!.includes(tag)) _.unset(paths[p], method);
+      })
+    });
+  }
+}
+
+interface SecurityOptions {
+  type?: string;
+  schema?: string;
+  bearerFormat?: string | null;
+  required?: boolean;
+}
+
+function security(name: string, {type = "http", schema = "bearer", bearerFormat = null, required = true}: SecurityOptions = {}): string {
+  components.securitySchemes = components.securitySchemes || {};
+  components.securitySchemes[name] = { type, scheme: schema, bearerFormat, "in": "header", required };
+  return `#/components/securitySchemes/${name}`;
+}
+
+interface RefOptions {
+  type: string;
+  name: string;
+  def: SwaggerSchema;
+}
+
+function _ref({ type, name, def }: RefOptions): string {
+  components[type] = components[type] || {};
+  (components[type] as any)[name] = def;
+  return `#/components/${type}/${name}`;
+}
+
+const ref = {
+  schema(name: string, flatSch: string): string {
+    return _ref({ type: "schemas", name, def: toSwaggerSchema(flatSch) });
+  }
+}
+
+function tag(name: string, description?: string): void {
+  tags.push({ name, description });
+}
+
+interface SwaggerDoc {
+  info: { title: string; version: string };
+  openapi: string;
+  servers: Server[];
+  tags: Tag[];
+  paths: Paths;
+  components: Components;
+}
+
+function swaggerDoc(title?: string): SwaggerDoc {
+  return {
+    info: { title: title || "", version: "1.0.0" },
+    openapi: "3.0.0",
+    servers,
+    tags,
+    paths,
+    components,
+  };
+}
+
+export {
+  tag,
+  server,
+  ref,
+  get,
+  post,
+  put,
+  patch,
+  del,
+  security,
+  swaggerDoc,
+  reset,
+  remove,
+};
+
+export type { ApiOptions, ApiExtension, SwaggerDoc };

package/src/utils.ts

@@ -0,0 +1,125 @@
+/**
+Author: Yusuf Bhabhrawala
+ */
+import * as _ from "lodash";
+// @ts-ignore
+import { typeShape } from "@sleeksky/alt-schema";
+
+const TYPES: { [key: string]: string } = { i: "integer", s: "string", b: "boolean", n: "number", o: "object", a: "array" };
+
+const RX_BRACE = /\{([^\}]+)\}/g;
+const RX_COLON = /\:([^\/]+)/g;
+
+interface SwaggerSchema {
+  type?: string;
+  items?: SwaggerSchema;
+  properties?: { [key: string]: SwaggerSchema };
+  example?: any;
+  required?: boolean;
+  $ref?: string;
+}
+
+function toSwaggerSchema(str: string): SwaggerSchema {
+  function traverse(schema: SwaggerSchema, obj: any): void {
+    if (_.isArray(obj)) {
+      schema.type = "array";
+      schema.items = {};
+      traverse(schema.items, obj[0]);
+    } else if (_.isObject(obj)) {
+      schema.type = "object";
+      schema.properties = {};
+      _.forOwn(obj, (v, k) => {
+        schema.properties![k] = {};
+        traverse(schema.properties![k], v);
+      });
+    } else {
+      let [optional, type, def] = (obj as string).split(":");
+      const isOptional = optional === '?';
+      if (isOptional) {
+        type = type || 'string';
+      }
+      if (['string','number','boolean','integer','array','object'].indexOf(type) < 0) type = "string";
+      schema.type = type;
+      if (def !== undefined && def !== '') {
+        if (type === 'number' || type === 'integer') {
+          schema.example = parseFloat(def);
+        } else if (type === 'boolean') {
+          schema.example = ['true','1'].indexOf(def) > -1;
+        } else {
+          schema.example = def;
+        }
+      }
+      if (!isOptional) schema.required = true;
+    }
+  }
+
+  try {
+    const obj = typeShape(str);
+    const schema: SwaggerSchema = {};
+    traverse(schema, obj);
+    return schema;
+  } catch (error) {
+    throw new Error(`Malformed schema: ${str}`);
+  }
+}
+
+interface PathParameter {
+  in: string;
+  name: string;
+  schema: { type: string; example?: string };
+  required: boolean;
+}
+
+function pathParameters(str: string): PathParameter[] {
+  let params: PathParameter[] = [];
+  let matches = str.match(RX_BRACE);
+  if (!matches) matches = str.match(RX_COLON);
+  if (matches) {
+    params = matches.map(m => {
+      let [p, def] = m.replace(/^[\{\:]/,"").replace(/[\}]$/,"").split(":");
+      if (!def) def = "";
+      return { in: "path", name: p, schema: { type: "string", example: def }, required: true };
+    });
+  }
+  return params;
+}
+
+function pathClean(path: string): string {
+  if (path.match(RX_BRACE)) return path.replace(RX_BRACE, m => `${m.split(/(\:.+)?\}/)[0]}}`)
+  return path;
+}
+
+interface Parameter {
+  name: string;
+  in: string;
+  required: boolean;
+  schema: { type: string; example?: string };
+}
+
+// header:?token
+function toParameter(inType: string, str: string | Parameter): Parameter {
+  if (!_.isString(str)) return str as Parameter;
+  const cleanStr = str.replace(/ /g, "");
+  let [name, type, def] = cleanStr.split(":");
+  let required = true;
+  if (type && type.match(/^\?/)) {
+    type = type.replace(/^\?/, "");
+    required = false;
+  }
+  if (type && TYPES[type]) type = TYPES[type];
+  else type = "string";
+  const schema: { type: string; example?: string } = { type };
+  if (def) schema.example = def;
+
+  return {
+    name,
+    in: inType,
+    required,
+    schema
+  };
+}
+
+export { toSwaggerSchema, pathParameters, pathClean, toParameter };
+export type { SwaggerSchema, PathParameter, Parameter };
+
+module.exports = {toSwaggerSchema, pathParameters, pathClean, toParameter};

package/src/index.js

@@ -1,171 +0,0 @@
-/**
-  Author: Yusuf Bhabhrawala
- */
-require("./utils");
-const _ = require("lodash");
-const { toSwaggerSchema, pathParameters, pathClean, toParameter} = require("./utils")
-
-const paths = {};
-const components = {};
-const tags = [];
-const servers = [];
-
-function reset() {
-  Object.keys(paths).forEach((key) => delete paths[key]);
-  Object.keys(components).forEach((key) => delete paths[key]);
-  tags.splice(0, tags.length);
-  servers.splice(0, servers.length);
-}
-
-function server(url, description) {
-  servers.push({ url, description });
-}
-
-function api(opt) {
-  let path = `${pathClean(opt.path)}.${opt.method}`;
-  let spec = _.get(paths, path, false);
-  if (!spec) {
-    spec = { parameters: [], responses: {}, description: "" };
-    const pathParams = pathParameters(opt.path);
-    if (pathParams.length > 0) spec.parameters = pathParams;
-    _.set(paths, path, spec);
-  }
-
-  let ext = {};
-
-  const req = (flatSch) => {
-    let schema = flatSch.match(/^#/) ? { $ref: flatSch } : toSwaggerSchema(flatSch);
-    spec.requestBody = {
-      content: { "application/json": { schema } },
-    };
-    return ext;
-  };
-  const res = (code, flatSch) => {
-    let schema = flatSch.match(/^#/) ? { $ref: flatSch } : toSwaggerSchema(flatSch);
-    spec.responses[code] = {
-      content: { [schema.type === "string" ? "text/plain" : "application/json"]: { schema } },
-      description: "",
-    };
-    return ext;
-  };
-  const query = (strArr) => {
-    if (!_.isArray(strArr)) strArr = strArr.split(",");
-    strArr.forEach((str) => {
-      spec.parameters.push(toParameter('query',str));
-    });
-    return ext;
-  };
-  const header = (strArr) => {
-    if (!_.isArray(strArr)) strArr = strArr.split(",");
-    strArr.forEach((str) => {
-      spec.parameters.push(toParameter('header',str));
-    });
-    return ext;
-  };
-  const tag = (str) => { spec.tags = [str]; return ext; };
-  const summary = (str) => { spec.summary = str; return ext; };
-  const desc = (str) => { spec.description = str; return ext; };
-  const security = (str) => { spec.security = [ { [str]: []}]; return ext; }
-  const deprecate = () => { spec.deprecated = true; return ext; };
-  const remove = () => { _.unset(paths, `${pathClean(opt.path)}.${opt.method}`); };
-
-  Object.assign(ext, { req, res, query, header, tag, summary, desc, deprecate, remove, security });
-
-  // support all ext in parameters
-  Object.keys(ext).forEach(k => {
-    if (opt[k]) ext[k](opt[k]);
-  });
-  Object.keys(opt).filter(k => k.match(/^[0-9]+$/)).forEach(k => ext.res(k, opt[k]));
-
-  return ext;
-}
-
-function get(path = "", opt = {}) {
-  opt.method = "get";
-  opt.path = path;
-  return api(opt);
-}
-
-function post(path = "", opt = {}) {
-  opt.method = "post";
-  opt.path = path;
-  return api(opt);
-}
-
-function put(path = "", opt = {}) {
-  opt.method = "put";
-  opt.path = path;
-  return api(opt);
-}
-
-function patch(path = "", opt = {}) {
-  opt.method = "patch";
-  opt.path = path;
-  return api(opt);
-}
-
-function del(path = "", opt = {}) {
-  opt.method = "delete";
-  opt.path = path;
-  return api(opt);
-}
-
-function remove({path=null, tag=null}) {
-  if (path) _.unset(paths, `${pathClean(path)}`);
-  if (tag) {
-    // remote all the paths with this tag
-    Object.keys(paths).forEach(p => {
-      Object.keys(paths[p]).forEach(method => {
-        if (paths[p][method].tags && paths[p][method].tags.includes(tag)) _.unset(paths[p], method);
-      })
-    });
-  }
-}
-
-function security(name, {type = "http", schema = "bearer", bearerFormat = null, required = true}) {
-  components.securitySchemes = components.securitySchemes || {};
-  components.securitySchemes[name] = { type, scheme: schema, bearerFormat, "in": "header", required };
-  return `#/components/securitySchemes/${name}`;
-}
-
-function _ref({ type, name, def }) {
-  components[type] = components[type] || {};
-  components[type][name] = def;
-  return `#/components/${type}/${name}`;
-}
-
-const ref = {
-  schema(name, flatSch) {
-    return _ref({ type: "schemas", name, def: toSwaggerSchema(flatSch) });
-  }
-}
-
-function tag(name, description) {
-  tags.push({ name, description });
-}
-
-function swaggerDoc(title) {
-  return {
-    info: { title: title || "", version: "1.0.0" },
-    openapi: "3.0.0",
-    servers,
-    tags,
-    paths,
-    components,
-  };
-}
-
-module.exports = {
-  tag,
-  server,
-  ref,
-  get,
-  post,
-  put,
-  patch,
-  del,
-  security,
-  swaggerDoc,
-  reset,
-  remove,
-};

package/src/utils.js

@@ -1,101 +0,0 @@
-/**
-Author: Yusuf Bhabhrawala
- */
-const _ = require("lodash");
-
-const {typeShape} = require("@sleeksky/alt-schema");
-
-const TYPES = {i: "integer", s: "string", b: "boolean", n: "number", o: "object", a: "array"};
-const RX_OBJ = /(\{[^\{\}\[\]]+\})/;
-const RX_ARR = /(\[[^\{\}\[\]]+\])/;
-const RX_NESTED = /^\:?(\$[0-9]+)$/;
-const RX_FLAT_ARR = /^\[([^\{\}\[\]]+)\]$/;
-const RX_FLAT_OBJ = /^\{([^\{\}\[\]]+)\}$/;
-
-const RX_BRACE = /\{([^\}]+)\}/g;
-const RX_COLON = /\:([^\/]+)/g;
-
-
-function toSwaggerSchema(str) {
-
-  function traverse(schema, obj) {
-    if (_.isArray(obj)) {
-      schema.type = "array";
-      schema.items = {};
-      traverse(schema.items, obj[0]);
-    } else if (_.isObject(obj)) {
-      schema.type = "object";
-      schema.properties = {};
-      _.forOwn(obj, (v, k) => {
-        schema.properties[k] = {};
-        traverse(schema.properties[k], v);
-      });
-    } else {
-      let [optional, type, def] = obj.split(":");
-      optional = (optional === '?') ? true : false;
-      if (['string','number','boolean','integer','array','object'].indexOf(type) < 0) type = "string"; 
-      schema.type = type;
-      if (def !== '') {
-        if (type === 'number' || type === 'integer') def = def*1;
-        if (type === 'boolean') def = ['true','1'].indexOf(def) > -1 ? true : false;
-        schema.example = def;
-      } else if (optional) {
-        // schema.default = null;
-      }
-      if (!optional) schema.required = true;
-    }
-  }
-
-  try {
-    let obj = typeShape(str);
-    let schema = {};
-    traverse(schema, obj);
-    return schema;
-  } catch (error) {
-    throw new Error(`Malformed schema: ${str}`);
-  }
-}
-
-function pathParameters(str) {
-  let params = [];
-  let matches = str.match(RX_BRACE);
-  if (!matches) matches = str.match(RX_COLON);
-  if (matches) {
-    params = matches.map(m => {
-      let [p, def] = m.replace(/^[\{\:]/,"").replace(/[\}]$/,"").split(":");
-      if (!def) def = "";
-      return { in: "path", name: p, schema: { type: "string", example: def }, required: true };
-    });
-  }
-  return params;
-}
-
-function pathClean(path) {
-  if (path.match(RX_BRACE)) return path.replace(RX_BRACE, m => `${m.split(/(\:.+)?\}/)[0]}}`)
-  return path;
-}
-
-// header:?token
-function toParameter(inType, str) {
-  if (!_.isString(str)) return str;
-  str = str.replace(/ /g, "");
-  let [name, type, def] = str.split(":");
-  let required = true;
-  if (type && type.match(/^\?/)) {
-    type = type.replace(/^\?/, "");
-    required = false;
-  }
-  if (type && TYPES[type]) type = TYPES[type];
-  else type = "string";
-  let schema = { type };
-  if (def) schema.example = def;
-
-  return {
-    name,
-    in: inType,
-    required,
-    schema
-  }
-}
-
-module.exports = {toSwaggerSchema, pathParameters, pathClean, toParameter};