https://github.com/coderofsalvation/expressa-swagger

genereated api documentation-page + restclients for expressa
https://github.com/coderofsalvation/expressa-swagger

Last synced: 9 months ago
JSON representation

genereated api documentation-page + restclients for expressa

• Host: GitHub
• URL: https://github.com/coderofsalvation/expressa-swagger
• Owner: coderofsalvation
• License: other
• Created: 2017-02-18T15:26:29.000Z (over 9 years ago)
• Default Branch: master
• Last Pushed: 2020-05-28T18:51:38.000Z (about 6 years ago)
• Last Synced: 2025-09-02T06:26:30.904Z (10 months ago)
• Language: JavaScript
• Size: 63.5 KB
• Stars: 3
• Watchers: 2
• Forks: 1
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE

Awesome Lists containing this project

README

          
Beautifully generated documentation + restclients for Express + [Expressa](https://npmjs.org/package/expressa) using swagger + markdown 

![](https://github.com/coderofsalvation/expressa-swagger/raw/master/expressa.png)

## 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](http://swagger.io/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