dpd-swagger-doc v1.1.11

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.