dpd-swagger-doc

automatically generated apidocs from deployd resources

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
dpd-swagger-doc
1.1.115 years ago6 years agoMinified + gzip package size for dpd-swagger-doc in KB

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 : nodemodules/dpd-swagger-doc/resource to resources/swagger
  • Create a folder in 'public' folder: 'apidoc'
  • Copy from: /nodemodules/dpd-swagger-doc/nodemodules/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.