├── .eslintignore ├── .eslintrc ├── app.js ├── test ├── fixtures │ └── apps │ │ └── swagger-test │ │ ├── package.json │ │ ├── config │ │ └── config.unittest.js │ │ └── app │ │ └── router.js └── swagger.test.js ├── .gitignore ├── agent.js ├── HISTORY.md ├── .travis.yml ├── config └── config.default.js ├── appveyor.yml ├── .autod.conf.js ├── .editorconfig ├── .github └── PULL_REQUEST_TEMPLATE.md ├── app ├── middleware │ └── swagger.js └── public │ ├── index.html │ └── template.html ├── LICENSE ├── package.json ├── README.zh_CN.md └── README.md /.eslintignore: -------------------------------------------------------------------------------- 1 | coverage 2 | node_modules 3 | app/public 4 | -------------------------------------------------------------------------------- /.eslintrc: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "eslint-config-egg" 3 | } 4 | -------------------------------------------------------------------------------- /app.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | // const assert = require('assert'); 3 | 4 | module.exports = () => { 5 | }; 6 | -------------------------------------------------------------------------------- /test/fixtures/apps/swagger-test/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "swagger-test", 3 | "version": "0.0.1" 4 | } 5 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | logs/ 2 | npm-debug.log 3 | node_modules/ 4 | coverage/ 5 | .idea/ 6 | run/ 7 | .DS_Store 8 | *.swp 9 | 10 | -------------------------------------------------------------------------------- /agent.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | module.exports = () => { 4 | // console.log('agent.config.env =', agent.config.env); 5 | }; 6 | -------------------------------------------------------------------------------- /HISTORY.md: -------------------------------------------------------------------------------- 1 | ## 20191216 2 | 3 | 1. 更新ui 版本 4 | 5 | ## 20171121 6 | 7 | 1. 移除 `swagger-jsdoc` 8 | 2. 功能简化, 仅处理 swagger-ui 部分 9 | 10 | ## 20170918 11 | 12 | 1. 移除谷歌字体 13 | 2. 使用 `min.js` 14 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | sudo: false 2 | language: node_js 3 | node_js: 4 | - '8' 5 | - '10' 6 | - '12' 7 | before_install: 8 | - npm i npminstall -g 9 | install: 10 | - npminstall 11 | script: 12 | - npm run ci 13 | after_script: 14 | - npminstall codecov && codecov 15 | -------------------------------------------------------------------------------- /config/config.default.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | module.exports = () => { 4 | const exports = {}; 5 | 6 | exports.swagger = { 7 | enable: true, 8 | mountPath: '/docs', 9 | swaggerFilePath: '/swagger.json', 10 | enableGoogleFont: false, 11 | }; 12 | 13 | return exports; 14 | }; 15 | -------------------------------------------------------------------------------- /test/fixtures/apps/swagger-test/config/config.unittest.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | exports.swagger = { 4 | enable: true, 5 | mountPath: '/test-mount', 6 | swaggerFilePath: '/test-swagger.json', 7 | enableGoogleFont: false, 8 | }; 9 | 10 | exports.middleware = [ 11 | 'swagger', 12 | ]; 13 | 14 | exports.keys = '123456'; 15 | -------------------------------------------------------------------------------- /appveyor.yml: -------------------------------------------------------------------------------- 1 | environment: 2 | matrix: 3 | - nodejs_version: '6' 4 | - nodejs_version: '8' 5 | 6 | install: 7 | - ps: Install-Product node $env:nodejs_version 8 | - npm i npminstall && node_modules\.bin\npminstall 9 | 10 | test_script: 11 | - node --version 12 | - npm --version 13 | - npm run test 14 | 15 | build: off 16 | -------------------------------------------------------------------------------- /.autod.conf.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | module.exports = { 4 | write: true, 5 | prefix: '^', 6 | plugin: 'autod-egg', 7 | test: [ 8 | 'test', 9 | 'benchmark', 10 | ], 11 | devdep: [ 12 | 'egg', 13 | 'egg-ci', 14 | 'egg-bin', 15 | 'autod', 16 | 'autod-egg', 17 | 'eslint', 18 | 'eslint-config-egg', 19 | 'supertest', 20 | 'webstorm-disable-index', 21 | ], 22 | exclude: [ 23 | './test/fixtures', 24 | './docs', 25 | './coverage', 26 | ], 27 | }; 28 | -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | # EditorConfig helps developers define and maintain consistent 2 | # coding styles between different editors and IDEs 3 | # http://editorconfig.org 4 | 5 | root = true 6 | 7 | [*] 8 | 9 | # Change these settings to your own preference 10 | indent_style = space 11 | indent_size = 2 12 | 13 | # We recommend you to keep these unchanged 14 | end_of_line = lf 15 | charset = utf-8 16 | trim_trailing_whitespace = true 17 | insert_final_newline = true 18 | 19 | # editorconfig-tools is unable to ignore longs strings or urls 20 | max_line_length = null 21 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | 10 | 11 | ##### Checklist 12 | 13 | 14 | - [ ] `npm test` passes 15 | - [ ] tests and/or benchmarks are included 16 | - [ ] documentation is changed or added 17 | - [ ] commit message follows commit guidelines 18 | 19 | ##### Affected core subsystem(s) 20 | 21 | 22 | 23 | ##### Description of change 24 | 25 | -------------------------------------------------------------------------------- /test/fixtures/apps/swagger-test/app/router.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | module.exports = app => { 4 | app.get('/', function* () { 5 | this.body = 'hi, ' + app.plugins.swagger.name; 6 | }); 7 | 8 | app.get('/test-swagger.json', function* () { 9 | const swagger = { 10 | swagger: '2.0', // swagger api version 11 | info: { 12 | description: 'rest api description', 13 | version: '1.0', 14 | title: 'rest api', 15 | termsOfService: '', 16 | contact: { 17 | email: '', 18 | }, 19 | license: { 20 | name: 'Apache 2.0', 21 | url: 'http://www.apache.org/licenses/LICENSE-2.0.html', 22 | }, 23 | }, 24 | host: 'petstore.swagger.io', 25 | basePath: '/v1', 26 | schemes: [ 'http' ], 27 | // Complex mode 28 | tags: [], 29 | paths: [], 30 | securityDefinitions: {}, 31 | definitions: [], 32 | }; 33 | this.body = swagger; 34 | }); 35 | }; 36 | -------------------------------------------------------------------------------- /app/middleware/swagger.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | const path = require('path'); 4 | const mount = require('koa-mount'); 5 | const send = require('koa-send'); 6 | const fs = require('fs'); 7 | const template = require('lodash.template'); 8 | const pathToSwaggerUi = require('swagger-ui-dist').absolutePath(); 9 | 10 | const publicPath = path.join(__dirname, '../', 'public'); 11 | const templatePath = path.join(publicPath, 'template.html'); 12 | const templateStr = fs.readFileSync(templatePath, 'utf8'); 13 | const compiled = template(templateStr); 14 | 15 | module.exports = options => { 16 | const swaggerFilePath = options.swaggerFilePath; 17 | const middle = async ctx => { 18 | const compiledOptions = { 19 | mountPath: options.mountPath, 20 | swaggerFilePath, 21 | enableGoogleFont: options.enableGoogleFont, 22 | }; 23 | if (ctx.path === '/') { 24 | ctx.body = compiled(compiledOptions); 25 | } else { 26 | await send(ctx, ctx.path, { root: pathToSwaggerUi }); 27 | } 28 | }; 29 | 30 | return mount(options.mountPath, middle); 31 | }; 32 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2017 Alibaba Group Holding Limited and other contributors. 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "egg-swagger", 3 | "version": "1.2.2", 4 | "description": "egg swagger doc", 5 | "eggPlugin": { 6 | "name": "swagger" 7 | }, 8 | "keywords": [ 9 | "egg", 10 | "eggPlugin", 11 | "egg-plugin" 12 | ], 13 | "dependencies": { 14 | "koa-mount": "^4.0.0", 15 | "koa-send": "^5.0.0", 16 | "lodash.template": "^4.5.0", 17 | "swagger-ui-dist": "^3.24.3" 18 | }, 19 | "devDependencies": { 20 | "autod": "^3.1.0", 21 | "autod-egg": "^1.1.0", 22 | "egg": "^2.26.0", 23 | "egg-bin": "^4.14.0", 24 | "egg-ci": "^1.13.1", 25 | "egg-mock": "^3.25.0", 26 | "eslint": "^6.7.2", 27 | "eslint-config-egg": "^8.0.0", 28 | "supertest": "^4.0.2", 29 | "webstorm-disable-index": "^1.2.0" 30 | }, 31 | "engines": { 32 | "node": ">=6.0.0" 33 | }, 34 | "scripts": { 35 | "test": "npm run lint -- --fix && egg-bin pkgfiles && npm run test-local", 36 | "test-local": "egg-bin test", 37 | "cov": "egg-bin cov", 38 | "lint": "eslint .", 39 | "ci": "egg-bin pkgfiles --check && npm run lint && npm run cov", 40 | "pkgfiles": "egg-bin pkgfiles", 41 | "autod": "autod" 42 | }, 43 | "files": [ 44 | "app", 45 | "config", 46 | "agent.js", 47 | "app.js" 48 | ], 49 | "ci": { 50 | "version": "6, 8" 51 | }, 52 | "repository": { 53 | "type": "git", 54 | "url": "git+https://github.com/eggjs/egg-swagger.git" 55 | }, 56 | "bugs": { 57 | "url": "https://github.com/eggjs/egg/issues" 58 | }, 59 | "homepage": "https://github.com/eggjs/egg-swagger#readme", 60 | "author": "", 61 | "license": "MIT" 62 | } 63 | -------------------------------------------------------------------------------- /README.zh_CN.md: -------------------------------------------------------------------------------- 1 | # egg-swagger 2 | 3 | [![NPM version][npm-image]][npm-url] 4 | [![build status][travis-image]][travis-url] 5 | [![Test coverage][codecov-image]][codecov-url] 6 | [![David deps][david-image]][david-url] 7 | [![Known Vulnerabilities][snyk-image]][snyk-url] 8 | [![npm download][download-image]][download-url] 9 | 10 | [npm-image]: https://img.shields.io/npm/v/egg-swagger.svg?style=flat-square 11 | [npm-url]: https://npmjs.org/package/egg-swagger 12 | [travis-image]: https://img.shields.io/travis/eggjs/egg-swagger.svg?style=flat-square 13 | [travis-url]: https://travis-ci.org/eggjs/egg-swagger 14 | [codecov-image]: https://img.shields.io/codecov/c/github/eggjs/egg-swagger.svg?style=flat-square 15 | [codecov-url]: https://codecov.io/github/eggjs/egg-swagger?branch=master 16 | [david-image]: https://img.shields.io/david/eggjs/egg-swagger.svg?style=flat-square 17 | [david-url]: https://david-dm.org/eggjs/egg-swagger 18 | [snyk-image]: https://snyk.io/test/npm/egg-swagger/badge.svg?style=flat-square 19 | [snyk-url]: https://snyk.io/test/npm/egg-swagger 20 | [download-image]: https://img.shields.io/npm/dm/egg-swagger.svg?style=flat-square 21 | [download-url]: https://npmjs.org/package/egg-swagger 22 | 23 | egg 插件，提供 swagger-ui 2.0. 24 | 25 | ## 依赖说明 26 | 27 | ### 依赖的 egg 版本 28 | 29 | egg-swagger 版本 | egg 1.x 30 | --- | --- 31 | 1.x | 😁 32 | 0.x | ❌ 33 | 34 | ### 依赖的插件 35 | 36 | 无 37 | 38 | ## 开启插件 39 | 40 | ```js 41 | // config/plugin.js 42 | exports.swagger = { 43 | enable: true, 44 | package: 'egg-swagger', 45 | }; 46 | ``` 47 | 48 | ## 使用场景 49 | 50 | - 提供像[swagger-ui](http://petstore.swagger.io/?_ga=2.67112721.1460016005.1511156320-1698683464.1510724052) 对外开放 restful api 51 | - How: 描述这个插件是怎样使用的，具体的示例代码，甚至提供一个完整的示例，并给出链接。 52 | 53 | ## 详细配置 54 | 55 | 请到 [config/config.default.js](config/config.default.js) 查看详细配置项说明。 56 | 57 | ## 单元测试 58 | 59 | 60 | 61 | ## 提问交流 62 | 63 | 请到 [egg issues](https://github.com/eggjs/egg/issues) 异步交流。 64 | 65 | ## License 66 | 67 | [MIT](LICENSE) 68 | -------------------------------------------------------------------------------- /test/swagger.test.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | const request = require('supertest'); 4 | const assert = require('assert'); 5 | const mm = require('egg-mock'); 6 | 7 | describe('test/swagger.test.js', () => { 8 | let app; 9 | before(() => { 10 | app = mm.app({ 11 | baseDir: 'apps/swagger-test', 12 | }); 13 | return app.ready(); 14 | }); 15 | 16 | after(() => app.close()); 17 | afterEach(mm.restore); 18 | 19 | it('should GET /', () => { 20 | return request(app.callback()) 21 | .get('/') 22 | .expect('hi, swagger') 23 | .expect(200); 24 | }); 25 | 26 | it('should GET /test-swagger.json', done => { 27 | const expected = { 28 | swagger: '2.0', // swagger api version 29 | info: { 30 | description: 'rest api description', 31 | version: '1.0', 32 | title: 'rest api', 33 | termsOfService: '', 34 | contact: { 35 | email: '', 36 | }, 37 | license: { 38 | name: 'Apache 2.0', 39 | url: 'http://www.apache.org/licenses/LICENSE-2.0.html', 40 | }, 41 | }, 42 | host: 'petstore.swagger.io', 43 | basePath: '/v1', 44 | schemes: [ 'http' ], 45 | // Complex mode 46 | tags: [], 47 | paths: [], 48 | securityDefinitions: {}, 49 | definitions: [], 50 | }; 51 | request(app.callback()) 52 | .get('/test-swagger.json') 53 | .set('Accept', 'application/json') 54 | .expect(200) 55 | .end(function(err, res) { 56 | if (err) return done(err); 57 | const actual = res.body; 58 | assert.deepEqual(actual, expected); 59 | done(); 60 | }); 61 | }); 62 | 63 | it('should GET /test-mount', done => { 64 | request(app.callback()) 65 | .get('/test-mount') 66 | .expect(200) 67 | .end(function(err, res) { 68 | if (err) return done(err); 69 | const actual = res.text; 70 | assert(actual); 71 | done(); 72 | }); 73 | }); 74 | 75 | it('should GET /test-mount/swagger-ui.css', done => { 76 | request(app.callback()) 77 | .get('/test-mount/swagger-ui.css') 78 | .expect(200) 79 | .end(function(err, res) { 80 | if (err) return done(err); 81 | const actual = res.text; 82 | assert(actual); 83 | done(); 84 | }); 85 | }); 86 | }); 87 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # egg-swagger 2 | 3 | [![NPM version][npm-image]][npm-url] 4 | [![build status][travis-image]][travis-url] 5 | [![Test coverage][codecov-image]][codecov-url] 6 | [![David deps][david-image]][david-url] 7 | [![Known Vulnerabilities][snyk-image]][snyk-url] 8 | [![npm download][download-image]][download-url] 9 | 10 | [npm-image]: https://img.shields.io/npm/v/egg-swagger.svg?style=flat-square 11 | [npm-url]: https://npmjs.org/package/egg-swagger 12 | [travis-image]: https://img.shields.io/travis/TheOne1006/egg-swagger.svg?style=flat-square 13 | [travis-url]: https://travis-ci.org/TheOne1006/egg-swagger 14 | [codecov-image]: https://img.shields.io/codecov/c/github/TheOne1006/egg-swagger.svg?style=flat-square 15 | [codecov-url]: https://codecov.io/github/TheOne1006/egg-swagger?branch=master 16 | [david-image]: https://img.shields.io/david/TheOne1006/egg-swagger.svg?style=flat-square 17 | [david-url]: https://david-dm.org/TheOne1006/egg-swagger 18 | [snyk-image]: https://snyk.io/test/npm/egg-swagger/badge.svg?style=flat-square 19 | [snyk-url]: https://snyk.io/test/npm/egg-swagger 20 | [download-image]: https://img.shields.io/npm/dm/egg-swagger.svg?style=flat-square 21 | [download-url]: https://npmjs.org/package/egg-swagger 22 | 23 | egg plugin，support swagger-ui 2.0. 24 | 25 | ## Install 26 | 27 | ```bash 28 | $ npm i egg-swagger --save 29 | ``` 30 | 31 | ## Usage 32 | 33 | ```js 34 | // {app_root}/config/plugin.js 35 | exports.swagger = { 36 | enable: true, 37 | package: 'egg-swagger', 38 | }; 39 | ``` 40 | 41 | ## Configuration 42 | 43 | ```js 44 | // {app_root}/config/config.default.js 45 | exports.swagger = { 46 | enable: true, 47 | mountPath: '/test-mount', // swagger-ui address /test-mount 48 | swaggerFilePath: '/test-swagger.json', // swagger file default path 49 | enableGoogleFont: false, 50 | }; 51 | ``` 52 | 53 | see [config/config.default.js](config/config.default.js) for more detail. 54 | 55 | ## Example 56 | 57 | - [swagger-ui](http://petstore.swagger.io/?_ga=2.67112721.1460016005.1511156320-1698683464.1510724052) 对外开放 restful api 58 | 59 | 60 | 61 | ## Tips 62 | 63 | 搭配 可直接生成对应的 swagger 数据 64 | 65 | ## 依赖说明 66 | 67 | swagger.json 规则来自于 68 | 69 | 70 | ## Questions & Suggestions 71 | 72 | Please open an issue [here](https://github.com/TheOne1006/egg-swagger/issues). 73 | 74 | ## License 75 | 76 | [MIT](LICENSE) 77 | -------------------------------------------------------------------------------- /app/public/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | Swagger UI 7 | 8 | 9 | 10 | 11 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 |
69 | 70 | 71 | 72 | 93 | 94 | 95 | 96 | -------------------------------------------------------------------------------- /app/public/template.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | Swagger UI 7 | <% if(enableGoogleFont) { %> 8 | 9 | <% } %> 10 | 11 | 12 | 13 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 |
71 | 72 | 73 | 74 | 100 | 101 | 102 | 103 | --------------------------------------------------------------------------------