koa-swagger-ui

    1.1.3 • Public • Published

    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

     
    const SwaggerAPI = require('joi-router-swagger-docs').SwaggerAPI;
    const Router = require('koa-joi-router');
    const Joi = Router.Joi;
    const router = router();
     
    router.get('/demo',{
       validate: {
          query: {
            name: joi.string().max(100).description('new user name')
          }
        },
        handler: async (ctx) => {
          ctx.status = 200;
          ctx.body = {status: 1, msg: 'hello world'};
        },
        swagger: {
          tags: ['demo'],
          responses: {
            200: {
              description: '查询域名',
              schema: joi.object({
                status: joi.number().integer().default(1),
                server: joi.string().default('js.cool')
              }).label('serverSuccess')
            }
          }
        }
      });
     
    router.get('/signup', {
      validate: {
        type: 'json',
        body: {
          name: Joi.string().max(100).description('new user name')
        },
        output: {
          200: {
            body: {
              userId: Joi.string().description('newly created user id')
            }
          }
        }
      },
      handler: function*() {
        // ...
      }
    });
     
    router.get('/about/:versionId', {
      swagger: {
        description: 'Anything in swagger is passed directly onto the swagger object for that path',
        parameters: [
          {name: 'versionId', in: 'path', description: 'this is a good way to get other items onto swagger object.'}
        ]
      },
      handler: function*() {
        // ...
      }
    })
     
    //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
    router.get('/user/:id/friends/:friendId', {
      validate: {
        path: Joi.object().keys({
          id: Joi.string().alphanum().max(24).description('id of user').required(),
          friendId: Joi.string().alphanum().max(24).description('id of user\'s friend'),
        })
        output: {
          200: {
            body: {
              userId: Joi.string().description('The friend of the user. they are pretty cool.')
            }
          }
        }
      },
      handler: function*() {
        // ...
      }
    });
     
    swaggerAPI = new SwaggerAPI();
    swaggerAPI.addJoiRouter(router);
     
    let spec = swaggerAPI.generateSpec({
      info: {
        title: 'Example API',
        description: 'API for creating and editing examples',
        version: '1.1'
      },
      basePath: '/api/v1'
    });
     
    console.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

    Keywords

    none

    Install

    npm i koa-swagger-ui

    DownloadsWeekly Downloads

    2

    Version

    1.1.3

    License

    MIT

    Unpacked Size

    19.7 kB

    Total Files

    10

    Last publish

    Collaborators

    • willin