{"id":20760521,"url":"https://github.com/blueoakjs/blueoak-server","last_synced_at":"2025-04-07T17:09:21.527Z","repository":{"id":24725013,"uuid":"28137103","full_name":"BlueOakJS/blueoak-server","owner":"BlueOakJS","description":"express.js-based, swagger-matic, server runtime","archived":false,"fork":false,"pushed_at":"2023-01-07T02:18:34.000Z","size":1162,"stargazers_count":140,"open_issues_count":29,"forks_count":26,"subscribers_count":39,"default_branch":"master","last_synced_at":"2024-04-14T10:56:16.155Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BlueOakJS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-12-17T12:50:43.000Z","updated_at":"2024-02-04T03:16:15.000Z","dependencies_parsed_at":"2023-01-14T01:29:54.589Z","dependency_job_id":null,"html_url":"https://github.com/BlueOakJS/blueoak-server","commit_stats":null,"previous_names":[],"tags_count":70,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueOakJS%2Fblueoak-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueOakJS%2Fblueoak-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueOakJS%2Fblueoak-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueOakJS%2Fblueoak-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BlueOakJS","download_url":"https://codeload.github.com/BlueOakJS/blueoak-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247694876,"owners_count":20980733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-17T10:14:06.543Z","updated_at":"2025-04-07T17:09:21.505Z","avatar_url":"https://github.com/BlueOakJS.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![BlueOak Logo](https://github.com/BlueOakJS/blueoak-server/wiki/images/blueoak.png)\n======\n\nBlueOak Server is a NodeJS framework for building RESTful APIs.\n\n[![Build Status](https://travis-ci.org/BlueOakJS/blueoak-server.svg?branch=master)](https://travis-ci.org/BlueOakJS/blueoak-server)\n[![npm version](https://img.shields.io/npm/v/blueoak-server.svg)](https://www.npmjs.com/package/blueoak-server)\n\nBlueOak Server is _swagger-matic_, that is, it maximizes the value of your Swagger API (now OpenAPI, but really this supports only V2) by using it to drive runtime behavior.  \nBlueOak Server loads your Swagger API, connects the paths it defines to your implementation code, exposes that API to the network, and validates that every request is well-formed per that API.\n\nCheck out the documentation on our wiki: \u003chttps://github.com/BlueOakJS/blueoak-server/wiki\u003e\n\n### Overview\n\nBlueOak Server combines some of the best Node libraries into a single tool for building RESTful APIs.  It uses Express under the covers, but adds many additional features:\n\n- Swagger integration\n- Easy configuration\n- Clustering\n- Logging\n- Dependency injection\n\nProjects use the following directory structure.\n\n```\n├── [your_project_name]/\n│   ├── index.js \u003c-- optional Main script\n│   ├── package.json\n|   ├── config/\n|   |     └── default.json\n│   ├── handlers/\n│   ├── services/\n│   ├── middleware/\n│   ├── swagger/\n```\n\n#### Handlers\n[Handlers](https://github.com/BlueOakJS/blueoak-server/wiki/Handlers) contain Express route-handling functions.  They can either be directly wired to routes on the Express _app_, or defined using Swagger.\n\nTo use the _app_ directly, simply create a js file in the handlers directory that exports an `init` function.\nThe `init` function is called during server startup and injected with the the _app_ automatically.\n\n```js\nexports.init = function(app) {\n  app.get('/', function(req, res) {\n    res.json({});\n  });\n}\n\n```\n\n#### Services\n[Services](https://github.com/BlueOakJS/blueoak-server/wiki/Services) do most of the heavy lifting.  Like handlers, services contain init functions that are called during server startup.  However, services can export other functions, and those functions can be invoked from handlers.\n\nHere's an example of a fizzbuzz service (services/fizzbuzz.js).  You'll notice it has an init method with two parameters, _logger_ and _callback_.  The _logger_ is a [built-in service](https://github.com/BlueOakJS/blueoak-server/wiki/Logging-Service) for logging.  The _callback_ is an optional parameter used for cases where services need to perform asynchronous operations during startup.  The service also exports a _getResult_ function.  Any service or handler with a dependency on _fizzbuzz_ can invoke `fizzbuzz.getResult`.\n\n```js\nexports.init = function(logger, callback) {\n  logger.info(\"Starting FizzBuzz service\");\n  callback();\n}\n\nexports.getResult = function(num) {\n    if (num % 15 === 0) {\n        return \"FizzBuzz\";\n    } else if (num % 3 === 0) {\n        return \"Fizz\";\n    } else if (num % 5 === 0) {\n        return \"Buzz\";\n    } else {\n        return num;\n    }\n};\n  \n```\n\nWe want to use that service from our handler, so we include `fizzbuzz` as a parameter of the `init` function.\nThe server will ensure that the fizzbuzz service is initialized during server startup and passed to the handler.\n\n```js\nexports.init = function(app, fizzbuzz) {\n\n  app.get('/fizzbuzz/:num', function(req, res) {\n    var num = req.params.num;\n    res.json({\n        result: fizzbuzz.getResult(num)\n     });\n  });\n  \n}\n```\n#### Third-party Services\nServices can be published as npm modules and pulled into projects through the `npm install` command.\n\nFor example, the bos-couchdb service adds the ability to connect to a CouchDB database.\nIt can be installed to a blueoak-server project using\n\n```bash\n$ npm install bos-couchdb --save\n```\n\nOnce installed, it can be used in any service or handler through the dependency-injected `bosCouchdb` parameter.\n\n```js\nexports.init = function(config, logger, bosCouchdb) {\n  var myDb = bosCouchdb.get('mydb');\n}\n\n```\n\n* [bos-couchdb](https://github.com/BlueOakJS/bos-couchdb) - service for connecting to CouchDB databases\n\n#### Config\n[Configuration](https://github.com/BlueOakJS/blueoak-server/wiki/Services#config) is stored in json files in the _config_ directory.  Values can be accessed through the `config` service in handers and services.  Configuration also supports layering on environment-specific config as well as encrypted values.\n\n```js\nexports.init = function(config) {\n  var myServiceConfig = config.get('myService');\n}\n```\n\n#### Middleware\n[Middleware](https://github.com/BlueOakJS/blueoak-server/wiki/Middleware) are similar to services but used to wire up Express middleware.  The _express_ section of the config determines which middleware is loaded and in which order.\n\n```json\n{\n  \"express\": {\n    \"middleware\": [\"csrf\", \"cors\", \"session\", \"body-parser\"]\n  }\n}\n```\n\n#### Swagger (OpenAPI)\n\n[Swagger](https://github.com/BlueOakJS/blueoak-server/wiki/Handlers#swagger) files in the _swagger_ directory are read during server startup and automatically wired up to handlers. Swagger files can be in either json or yaml formats.\n\nWe've really focused on making API development with Swagger and BlueOak Server to be excellent.\n\nAt a high-level, BlueOak Server's Swagger support provides the following:\n* Automatic app routing from the API method to the function as defined in the Swagger\n* Request parameter validation, including the body model, based on your method definion\n* Reponse model validation based on your method definitions during development\n* JSON `$ref`s to external Swagger documents on the file system\n* Multiple top-level Swagger API definitions supporting delivery of multiple API base paths\n* Publishing of the fully compiled Swagger spec for input to by tools such as [`Swagger-UI`](http://swagger.io/swagger-ui/) and [`swagger-commander`](https://www.npmjs.com/package/swagger-commander)\n\n### Installation\n\n```bash\n$ npm install -g blueoak-server\n```\n\n-or-\n\n```bash\n$ npm install --save blueoak-server\n```\n\n### Usage\n\nIf installed globally, run _blueoak-server_ from within your project's directory.\ne.g.:\n```bash\n$ blueoak-server\n```\n\nIf installed at a package level, call _blueoak-server_ in the `npm start` script.\ne.g.:\n```json\n  \"scripts\": {\n    \"start\": \"blueoak-server\"\n  }\n```\n\nAlternatively, it can be launched programmatically from your own js script.\n\n\n```js\nvar server = require('blueoak-server');\n\nserver.init(function(err) {\n    if (err) {\n        console.warn(err);\n    } else {\n        console.log('started');\n    }\n});\n```\n\nThe programmatic approach works well during development with tools like nodemon,\nwhich monitor for file changes and automatically restart the server.\n\n### Next steps\n\nRead through the [docs](https://github.com/BlueOakJS/blueoak-server/wiki) and look at the our [examples](/examples).\n\nWhen you're ready to try it out, start from the [template](https://github.com/BlueOakJS/blueoak-server-template).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblueoakjs%2Fblueoak-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblueoakjs%2Fblueoak-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblueoakjs%2Fblueoak-server/lists"}