expressa-swagger

    1.0.13 • Public • Published

    Beautifully generated documentation + restclients for Express + Expressa using swagger + markdown

    Features

    • generates online documentation at /api/doc
    • generates swagger json at /api/swagger

    Usage

    npm install expressa-swagger --save
    

    NOTE: windows users need to make their own symlinks (see 'postinstall' in package.json)

    Then add this snippet to your expressa application:

    var expressaSwagger = require('expressa-swagger')
    expressaSwagger({
      express: express, 
      expressa: expressa, 
      app: app, 
      url: '/api/doc', 
      title: 'My appname', 
      description: "Lorem ipsum `markdown`",  // or just pass  __dirname+"/API.md" e.g.
      version: '1.0.0', 
      basepath: '/api', 
      schemes: ["http"], 
      onDocumentation: function(swagger, req, res, next){
        // optionally hide/modify swagger data here, or add auth middleware 
        // before serving it to the documentation generator at /api/doc
      }
    })
    

    Grab REST-clients for almost any language using swagger-codegen.

    NOTE: For the browser & nodejs, the recommended REST-client is [expressa-restclient](https://npmjs.org/package/expressa-restclient]

    Adhoc endpoint documentation

    Anywhere in your expressa-app, you can add documentation for endpoints like so:

    expressa.swagger.addEndpoint("get", "my/custom/endpoint",{
      "parameters": [
        {
          "in": "body",
          "name": "payload",
          "description": "", 
          "required": true,
          "schema": {
            "type": "object",
            "required":["id_user"],                  // see swagger
            "properties": {                          // documentation
              "id_user":{
                "required":true, 
                "type":"string",
                "default":"lLK34LK" 
              }
            }
          }
        }    
      ],
      "responses": { },
      "tags": [ "users" ],
      "summary": "Lorem ipsum"
    })
    

    Todo

    • option boolean to authenticate user + only show those endpoints/methods/properties which user has access to

    Keywords

    none

    Install

    npm i expressa-swagger

    DownloadsWeekly Downloads

    0

    Version

    1.0.13

    License

    ISC

    Last publish

    Collaborators

    • coderofsalvation