koa-swagger-ui

Still missing:

• convert route outputs into swagger
• finish converting from joi-to-json-schema to joi-to-swagger (there's no npm link, but there is a github link)
• make tests to demonstrate
• find out why swagger-cli throws validate errors on anything I create.

A node module for generating Swagger 2.0 JSON definitions from existing koa-joi-router routes.

Example

1
2const SwaggerAPI = require('joi-router-swagger-docs').SwaggerAPI;
3const Router = require('koa-joi-router');
4const Joi = Router.Joi;
5const router = router();
6
7router.get('/demo',{
8   validate: {
9      query: {
10        name: joi.string().max(100).description('new user name')
11      }
12    },
13    handler: async (ctx) => {
14      ctx.status = 200;
15      ctx.body = {status: 1, msg: 'hello world'};
16    },
17    swagger: {
18      tags: ['demo'],
19      responses: {
20        200: {
21          description: '查询域名',
22          schema: joi.object({
23            status: joi.number().integer().default(1),
24            server: joi.string().default('js.cool')
25          }).label('serverSuccess')
26        }
27      }
28    }
29  });
30
31router.get('/signup', {
32  validate: {
33    type: 'json',
34    body: {
35      name: Joi.string().max(100).description('new user name')
36    },
37    output: {
38      200: {
39        body: {
40          userId: Joi.string().description('newly created user id')
41        }
42      }
43    }
44  },
45  handler: function*() {
46    // ...
47  }
48});
49
50router.get('/about/:versionId', {
51  swagger: {
52    description: 'Anything in swagger is passed directly onto the swagger object for that path',
53    parameters: [
54      {name: 'versionId', in: 'path', description: 'this is a good way to get other items onto swagger object.'}
55    ]
56  },
57  handler: function*() {
58    // ...
59  }
60})
61
62//if you use swagger-ui you will want path parameters so people can use the 'try it out' functionality, despite the fact that koa-joi-router doesn't support them
63router.get('/user/:id/friends/:friendId', {
64  validate: {
65    path: Joi.object().keys({
66      id: Joi.string().alphanum().max(24).description('id of user').required(),
67      friendId: Joi.string().alphanum().max(24).description('id of user\'s friend'),
68    })
69    output: {
70      200: {
71        body: {
72          userId: Joi.string().description('The friend of the user. they are pretty cool.')
73        }
74      }
75    }
76  },
77  handler: function*() {
78    // ...
79  }
80});
81
82swaggerAPI = new SwaggerAPI();
83swaggerAPI.addJoiRouter(router);
84
85let spec = swaggerAPI.generateSpec({
86  info: {
87    title: 'Example API',
88    description: 'API for creating and editing examples',
89    version: '1.1'
90  },
91  basePath: '/api/v1'
92});
93
94console.log(JSON.stringify(spec, null, '  '));

API

new SwaggerAPI()

Creates a new SwaggerAPI instance.

swaggerAPI.addJoiRouter(router, options)

Add a joi-router instance to the API. The router should already have all its routes set up before calling this method (which pulls the route definitions from the router's .routes property).

Options:

• prefix: Prefix to add to Swagger path

swaggerAPI.generateSpec(baseSpec)

Create a Swagger specification for this API. A base specification should be provided with an info object (containing at least the title and version strings) and any other global descriptions.

Thanks for starting this:

Pebble Technology!

License

MIT