{"id":18742093,"url":"https://github.com/whlshy/usefulexpressapi","last_synced_at":"2026-04-05T23:32:51.490Z","repository":{"id":196404842,"uuid":"342267388","full_name":"whlshy/UsefulExpressAPI","owner":"whlshy","description":"Trying to build a useful API on NodeJs Express.","archived":false,"fork":false,"pushed_at":"2022-11-14T08:49:20.000Z","size":1714,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-20T05:38:48.028Z","etag":null,"topics":["express","mssql","nodejs","rest-api","runsql","schema-sql","swagger-ui","usefulapi"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/whlshy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-02-25T14:16:23.000Z","updated_at":"2022-12-01T07:42:12.000Z","dependencies_parsed_at":null,"dependency_job_id":"9bda111b-a75c-48e3-add5-1fb5f1a4682c","html_url":"https://github.com/whlshy/UsefulExpressAPI","commit_stats":null,"previous_names":["whlshy/usefulexpressapi"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/whlshy/UsefulExpressAPI","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whlshy%2FUsefulExpressAPI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whlshy%2FUsefulExpressAPI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whlshy%2FUsefulExpressAPI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whlshy%2FUsefulExpressAPI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/whlshy","download_url":"https://codeload.github.com/whlshy/UsefulExpressAPI/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whlshy%2FUsefulExpressAPI/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31454197,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T21:22:52.476Z","status":"ssl_error","status_checked_at":"2026-04-05T21:22:51.943Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["express","mssql","nodejs","rest-api","runsql","schema-sql","swagger-ui","usefulapi"],"created_at":"2024-11-07T16:06:16.283Z","updated_at":"2026-04-05T23:32:51.484Z","avatar_url":"https://github.com/whlshy.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# UsefulExpressAPI\n\n利用 Express 與 Swagger 結合起來的 API Model，採用 REST API 原則，並可以自動產生出 Swagger 文件與配合 schema 所定義的型別。\n\n## Contents\n- [Installation](#installation)\n- [Usage](#usage)\n  - [DataBase Config](#dbconfig)\n  - [Swagger Setting](#Swagger)\n  - [執行](#執行)\n  - [Add New Controller](#Controller)\n  - [Run SQL and Schema](#SQL_and_Schema)\n    - [runSQL](#runSQL)\n    - [Schema](#Schema)\n    - [Use Schema](#UseSchema)\n- [Example](#Example)\n\n\n## Installation\n全域安裝套件。\n```bash\nnpm i -g\n```\n將套件安裝在專案裡。\n```bash\nnpm i\n```\n## Usage\n### dbconfig\n資料庫：MSSQL\n\n**設定連線資訊 File：dbconfig.json**\n```json\n{\n    \"user\": \"travel\",\n    \"password\": \".travel.\",\n    \"server\": \"10.21.20.101\",\n    \"database\": \"TravelTest_6\",\n    \"options\": {\n        \"encrypt\": true,\n        \"enableArithAbort\": true\n    }\n}\n```\n\n### Swagger\n透過 Swagger 來製作線上版 API 規格文件\n\n**檔案簡單設定：swagger.js**\n```js\nconst doc = {\n    info: {\n        title: \"Travel API Document\",\n        description: \"Description\"\n    },\n    host: \"localhost:3000\",\n    schemes: ['http'],\n}\n```\n詳情可以參考此套件：[swagger-autogen](https://github.com/davibaltar/swagger-autogen)\n\n### 執行\n第一次執行請先生成 Swagger 設定檔後再啟動 API Server\n\n#### **生成 Swagger 設定檔執行**\n```bash\nnode .\\swagger.js\n```\n\n#### **啟動 API SERVER**\n```bash\nnpm run start\n```\nor\n```bash\nnode .\\index.js\n```\nor use nodemon (修改文件不用重新啟動)\n```bash\nnodemon .\\index.js\n```\n\n### Controller\n新增 Controller\n\n在 ./src/controllers 資料夾中建立新的 js\n\n**Exameple：create new file travel.js in './src/controllers'**\n```js\nvar express = require('express');\nvar router = express.Router();\n\nrouter.get('/travel/example', async (req, res, next) =\u003e {  // method GET\n    // #swagger.tags = ['travel']\n    res.send('這是 Travel 測試 API！')\n});\n\nmodule.exports = router;\n```\n\nAdd router for Travel.js\n\n**File：./src/controllers/index.js**\n```js\nvar Travel = require('./Travel');  // 引入 Travel.js\napp.use('/api', Travel)                        // 新增 router 路徑\n```\n重新生成 Swagger UI 後打開連結文件測試API\n\n[localhost:3000/api-doc](http://localhost:3000/api-doc)\n\n或者直接貼上網址\n\n[localhost:3000/api/travel/example](http://localhost:3000/api/travel/example)\n\n![image](https://user-images.githubusercontent.com/49122960/109974869-f826dd00-7d34-11eb-8292-8213d10eff9c.png)\n\n### SQL_and_Schema\n\n#### runSQL\n如果想要執行 SQL 語法\n\n引入 Lib 中的 runSQL.js：\n```js\nconst runSQL = require('../lib/runSQL')\n```\n參數：\n```js\nrunSQL(sqlcode, req, schema)  // SQL語法, 所有request, SQL參數型別定義\n```\n第一個範例先暫時不用到SQL參數，只先傳一個SQL語法到runSQL之中\n\n**File: travel.js**\n```js\nvar express = require('express');\nvar router = express.Router();\nvar runSQL = require('../lib/runSQL')\n\nrouter.get('/travel/getcity', async (req, res, next) =\u003e {  // method GET\n    // #swagger.tags = ['travel']\n    let sqlcode = \"select CID, CName, NamePath from Class where nLevel = 3\" // 要執行的 SQL 語法\n    let response = await runSQL(sqlcode)\n    res.json(response)\n});\n\nmodule.exports = router;\n```\n![image](https://user-images.githubusercontent.com/49122960/109981207-a9307600-7d3b-11eb-92f4-d450a5f609a0.png)\n\n#### Schema\n定義在 SQL 中變數的型別\n\n在 './src/schema' 當中新增檔案 travel.json\n\n**Example File: travel.json**\n```json\n[\n    { \"attr\": \"cid\", \"type\": \"Int\" },\n    { \"attr\": \"oid\", \"type\": \"Int\" }\n]\n```\n| attr | type |\n|-----|-----|\n| 變數名稱 | SQL型別 |\n\n在 **Swagger UI** 中，如果 tags 與 schema 名子一致則會自動帶入 schema 的型別\n\n在 **runSQL** 中傳入 schema 則會比對 sqlcode 中的 input 與 schema 中的 attr，並帶入 SQL 型別\n\n#### UseSchema\n有傳入變數的版本\n\n在 js 中引入 schema\n```js\nconst schema = require('../schema/travel.json')  // travel.js 用到的 sql 變數都會在這個 travel.json 當中定義\n```\n\n## Example\n**getCCData GET**\n```js\nconst schema = require('../schema/travel.json')  // 作為 runSQL 中第三個參數\n\nrouter.get('/travel/getCCData', async (req, res, next) =\u003e {  // method GET\n    // #swagger.tags = ['travel']\n    let { cid } = req.query  // 為 swagger ui 宣告有一個 query 叫 cid\n    let sqlcode = \"select PCID 'pcid', P.CName 'cname', CCID 'ccid', C.CName 'pname', P.NamePath 'namepath' from Class P, Inheritance I, Class C where P.CID = I.PCID and I.CCID = C.CID and P.CID = @cid\" // 要執行的 SQL 語法\n    let response = await runSQL(sqlcode, req, schema)\n    res.json(response)\n});\n```\n![image](https://user-images.githubusercontent.com/49122960/109989492-82763d80-7d43-11eb-84ad-6b7ec3ace3ff.png)\n\n**getCOData POST**\n```js\nrouter.post('/travel/getCOData', async (req, res, next) =\u003e {  // method POST\n    // #swagger.tags = ['travel']\n    let { cid } = req.body  // 為 swagger ui 宣告有一個 body 叫 cid\n    let sqlcode = \"select C.NamePath 'namepath', O.OID 'oid', O.Title 'title', O.Class 'district' from Class C, CO, Object O where C.CID = CO.CID and CO.OID = O.OID and C.CID = @cid\" // 要執行的 SQL 語法\n    let response = await runSQL(sqlcode, req, schema)\n    res.json(response)\n});\n```\n![image](https://user-images.githubusercontent.com/49122960/109995249-172f6a00-7d49-11eb-8a25-11a1fbb365a9.png)\n\n![image](https://user-images.githubusercontent.com/49122960/109995433-3e863700-7d49-11eb-800a-b2632a46b6da.png)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhlshy%2Fusefulexpressapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwhlshy%2Fusefulexpressapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhlshy%2Fusefulexpressapi/lists"}