https://github.com/coderofsalvation/dpd-swagger-doc

automatically generated apidocs from deployd resources
https://github.com/coderofsalvation/dpd-swagger-doc

Last synced: 12 days ago
JSON representation

automatically generated apidocs from deployd resources

• Host: GitHub
• URL: https://github.com/coderofsalvation/dpd-swagger-doc
• Owner: coderofsalvation
• License: mit
• Created: 2016-11-12T02:58:45.000Z (about 8 years ago)
• Default Branch: master
• Last Pushed: 2020-05-28T18:50:22.000Z (over 4 years ago)
• Last Synced: 2024-08-08T19:40:59.713Z (3 months ago)
• Language: JavaScript
• Size: 116 KB
• Stars: 6
• Watchers: 2
• Forks: 2
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE

Awesome Lists containing this project

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.