npm:dpd-swagger-doc

README

generate beautiful online swagger docs based on your deployd resources

Features

automatic documentation for Collection resources
automatic documentation for UserCollection resources
Custom/Collection/UserCollection-resources can be hinted in config.json

Usage: linux

$ cd your-deployd-dir
$ npm install dpd-event dpd-swagger-doc dpd-event-extension

Now copy the swagger-resource and symlink the swaggerfolder:

$ cp -R node_modules/dpd-swagger-doc/resource resources/swagger
$ cp -R node_modules/dpd-swagger-doc/node_modules/swagger-ui/dist public/apidoc

Done! now try: http://localhost:2403/apidoc/?url=/swagger#!/default

Usage: windows/mac

npm install dpd-event dpd-swagger-doc dpd-event-extension
Copy : node_modules/dpd-swagger-doc/resource to resources/swagger
Create a folder in 'public' folder: 'apidoc'
Copy from: /node_modules/dpd-swagger-doc/node_modules/swagger-ui/dist to public/apidoc

Done! now try http://localhost:2403/apidoc/?url=/swagger#!/default

Now what?

swagger json (should be) automatically generated at endpoint /swagger
surf to http://localhost/apidoc/?url=/swagger#!/default to see the generated docs
tweak resource/swagger/get.js at will

Hinting documentation

Swagger will peek into your resource's config.json for swagger snippets. This will allow you to extend the automatic documentation for (User)Collections. For Custom resources however, you always need to define them:

{
  "type": "Collection",                
  "properties": {
    "createdBy": {
        "name": "createdBy",
        "type": "string",
        "typeLabel": "string",
        "required": false,
        "id": "createdBy",
        "default":"username",                     <--  add this for autogenerated mock payloads 
        "order": 0
    },

    ....

  }
  "swagger":{                                     <--
    "methods":{                                   <--
      "get": {                                    <-- this is where the swagger extending 
        "public":true,                            <-- starts.. 
        "description": "Creates a item",          <--
        "produces": [ "application/json" ]        <-- for more see swagger 2 specs or just
      }                                           <-- peek here: http://petstore.swagger.io/v2/swagger.json
    }                                             <--
  }
}

NOTE: it is not needed to specify get/post/put/delete sections, since they are automatically generated for UserCollections & Collections. However, as shown above you can overload them (just peek at the /swagger-output in your browser)

Troubleshooting (MAC)

Error loading module node_modules/brace
ReferenceError: window is not define

Perform these steps below, on the Mac when you get the above error: 1.npm uninstall brace 2.npm uninstall fbjs 3.npm uninstall lodash-es

NOTE: It might throw some error on the console for certain functions and headers being missed. But it'll not be something to worry about.

Usage no npm install needed!