feat: Initial version.

Author: ShogunPanda

.eslintrc.json

@@ -0,0 +1,7 @@
+{
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "project": "tsconfig.test.json"
+  },
+  "extends": ["@cowtech/eslint-config/typescript"]
+}

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+---
+name: CI
+on: [push, pull_request]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v1
+      - name: Use Node.js LTS
+        uses: actions/setup-node@v1
+        with:
+          node-version: 14.x
+      - name: Restore cached dependencies
+        uses: actions/cache@v1
+        with:
+          path: node_modules
+          key: node-modules-${{ hashFiles('package.json') }}
+      - name: Install dependencies
+        run: npm install
+      - name: Run Tests
+        run: npm run ci
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v1
+        with:
+          file: ./coverage/coverage-final.json
+          token: ${{ secrets.CODECOV_TOKEN }}

.gitignore

@@ -0,0 +1,12 @@
+package-lock.json
+yarn.lock
+
+.nyc_output
+coverage/
+node_modules/
+tmp/
+
+npm-debug.log
+npm-error.log
+yarn-debug.log
+yarn-error.log

CHANGELOG.md

@@ -0,0 +1,3 @@
+### 2021-01-01 / 0.1.0
+
+- Initial version.

LICENSE.md

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2021, and above Shogun <shogun@cowtech.it>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

README.md

@@ -0,0 +1,157 @@
+# fastify-openapi-docs
+
+[![Package Version](https://img.shields.io/npm/v/fastify-openapi-docs.svg)](https://npm.im/fastify-openapi-docs)
+[![Dependency Status](https://img.shields.io/david/ShogunPanda/fastify-openapi-docs)](https://david-dm.org/ShogunPanda/fastify-openapi-docs)
+[![Build](https://github.com/ShogunPanda/fastify-openapi-docs/workflows/CI/badge.svg)](https://github.com/ShogunPanda/fastify-openapi-docs/actions?query=workflow%3ACI)
+[![Code Coverage](https://img.shields.io/codecov/c/gh/ShogunPanda/fastify-openapi-docs?token=d0ae1643f35c4c4f9714a357f796d05d)](https://codecov.io/gh/ShogunPanda/fastify-openapi-docs)
+
+A simple plugin for Fastify that generates OpenAPI spec automatically.
+
+http://sw.cowtech.it/fastify-openapi-docs
+
+## Installation
+
+Just run:
+
+```bash
+npm install fastify-openapi-docs --save
+```
+
+## Usage
+
+Register as a plugin as early as possible (in order to track all routes), optional providing any of the following options:
+
+- `openapi`: The OpenAPI document header.
+- `prefix`: Where to serve the OpenAPI files. The default value is `/docs/`.
+- `skipUI`: If set `true`, the the OpenAPI / Swagger UI will not be served.
+
+Routes should contain a `openapi` object inside the `config` with all desired OpenAPI annotations.
+
+Non JSON responses can be generated by setting the `$raw` key in the response schema to the appropriate MIME type.
+
+Empty responses can be generated by setting the `$empty` key in the response schema to `true`.
+
+Routes can be omitted from spec by the list by setting `hide` option to `true` inside their `config`.
+
+Once the server is started, it will serve the OpenAPI specification on both `/{prefix}/openapi.json` and `/{prefix}/openapi.yaml`.
+
+If the UI is enabled, it will be reachable at `/${prefix}`.
+
+## Example
+
+```js
+const server = require('fastify')()
+
+server.register(require('fastify-openapi-docs'), {
+  openapi: {
+    // All these fields are optional, but they should be provided to satisfy OpenAPI specification.
+    openapi: '3.0.3',
+    info: {
+      title: 'Title',
+      description: 'Description',
+      contact: {
+        name: 'Shogun',
+        url: 'https://cowtech.it',
+        email: 'shogun@cowtech.it'
+      },
+      license: {
+        name: 'ISC',
+        url: `https://choosealicense.com/licenses/isc/`
+      },
+      version: '1.0.0'
+    },
+    servers: [
+      { url: 'https://example.com', description: 'Production Server' },
+      { url: 'https://dev.example.com', description: 'Development Server' }
+    ],
+    tags: [{ name: 'service', description: 'Service' }],
+    components: {
+      securitySchemes: {
+        jwtBearer: {
+          type: 'http',
+          scheme: 'bearer',
+          bearerFormat: 'JWT'
+        }
+      }
+    }
+  }
+})
+
+server.addSchema({
+  type: 'object',
+  $id: '#request',
+  description: 'The request payload',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'The operation id',
+      pattern: '^.+$',
+      example: true
+    }
+  },
+  required: ['id'],
+  additionalProperties: false
+})
+
+server.addSchema({
+  type: 'object',
+  $id: '#response',
+  description: 'The response payload',
+  properties: {
+    ok: {
+      type: 'boolean',
+      description: 'The operation response',
+      example: true
+    }
+  },
+  required: ['ok'],
+  additionalProperties: false
+})
+
+server.route({
+  method: 'POST',
+  url: '/path',
+  schema: {
+    body: { $ref: '#request' },
+    response: {
+      200: { $ref: '#response' }
+    }
+  },
+  config: {
+    openapi: {
+      description: 'Makes a request',
+      summary: 'Main route',
+      tags: ['service'],
+      security: [{ jwtBearer: [] }]
+    }
+  },
+  handler(_, reply) {
+    reply.send({ ok: true })
+  }
+})
+
+server.listen(3000)
+```
+
+Once started, the following routes will be available:
+
+- `http://localhost:3000/docs/openapi.yaml`
+- `http://localhost:3000/docs/openapi.json`
+- `http://localhost:3000/docs` (OpenAPI UI)
+
+Note that `$ref` in the schemas will be resolved and replaced accordingly to OpenAPI spec.
+
+## Contributing to fastify-openapi-docs
+
+- Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+- Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+- Fork the project.
+- Start a feature/bugfix branch.
+- Commit and push until you are happy with your contribution.
+- Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+
+## Copyright
+
+Copyright (C) 2021 and above Shogun (shogun@cowtech.it).
+
+Licensed under the ISC license, which can be found at https://choosealicense.com/licenses/isc.

lib/index.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.plugin = void 0;
+const fastify_plugin_1 = __importDefault(require("fastify-plugin"));
+const js_yaml_1 = require("js-yaml");
+const spec_1 = require("./spec");
+const ui_1 = require("./ui");
+exports.plugin = fastify_plugin_1.default(function (instance, options, done) {
+    var _a, _b;
+    let prefix = (_a = options.prefix) !== null && _a !== void 0 ? _a : '/docs';
+    let spec = (_b = options.openapi) !== null && _b !== void 0 ? _b : {};
+    const routes = [];
+    if (prefix.indexOf('/') !== 0) {
+        prefix = `/${prefix}`;
+    }
+    if (!options.skipUI) {
+        ui_1.addUI(instance, prefix);
+    }
+    // Register spec routes
+    instance.route({
+        method: 'GET',
+        url: `${prefix}/openapi.yaml`,
+        handler(_, reply) {
+            reply.type('text/yaml');
+            reply.send(js_yaml_1.dump(spec));
+        },
+        config: { hide: false }
+    });
+    instance.route({
+        method: 'GET',
+        url: `${prefix}/openapi.json`,
+        handler(_, reply) {
+            reply.send(spec);
+        },
+        config: { hide: false }
+    });
+    // Utility to track all the RouteOptions we add
+    instance.addHook('onRoute', (route) => {
+        routes.push(route);
+    });
+    // When the server starts, add all schemas and routes to the spec
+    instance.addHook('onReady', (done) => {
+        spec = spec_1.buildSpec(instance, spec, instance.getSchemas(), routes);
+        done();
+    });
+    done();
+}, { name: 'fastify-openapi-docs' });
+exports.default = exports.plugin;
+module.exports = exports.plugin;
+Object.assign(module.exports, exports);