Hi, @fsbahman, in this example, will generate the incorrect swagger.json file.

/**
 * @api {post} /users Request CreateUsers
 * @apiName CreateUsers
 * @apiGroup User
 *
 * @apiParam {Object[]}     users         User list.
 * @apiParam {String}       users.id      UUID of user.
 * @apiParam {String}       users.name    Name of user.
 *
 * @apiSuccess {String}     status        Status of request.
 * @apiSuccess {Object[]}   users         User list.
 * @apiSuccess {String}     users.id      UUID of user.
 * @apiSuccess {String}     users.name    Name of user.
 */

1. it's doesn't work in "Object[]".
   because it could not find the items type "Object" ( maybe should use "$refs"?)

...
 "definitions": {
        "CreateUsers": {
            "properties": {
                "users": {
                    "type": "array",
                    "description": "User list.",
                    "items": {
                        "type": "Object"
                    }
                },
...

2. it's doesn't work in multiple "@apiSuccess".
   in this example, the responses.schema.type should not be "String", "String" is the first @apiSuccess type

...
                "responses": {
                    "200": {
                        "description": "successful operation",
                        "schema": {
                            "type": "String",
                            "items": {
                                "$ref": "#/definitions/CreateUsers"
                            }
                        }
                    }
                }
...

Here is the complete output swagger.json file:

{
    "swagger": "2.0",
    "info": {
        "title": "test",
        "version": "1.0.0",
        "description": "Test project description"
    },
    "paths": {
        "/users": {
            "post": {
                "tags": [
                    "User"
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "in": "body",
                        "name": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/CreateUsers"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "successful operation",
                        "schema": {
                            "type": "String",
                            "items": {
                                "$ref": "#/definitions/CreateUsers"
                            }
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "CreateUsers": {
            "properties": {
                "users": {
                    "type": "array",
                    "description": "User list.",
                    "items": {
                        "type": "Object"
                    }
                },
                "status": {
                    "type": "string",
                    "description": "Status of request."
                }
            },
            "required": [
                "users",
                "status"
            ]
        },
        "users": {
            "properties": {
                "id": {
                    "type": "string",
                    "description": "UUID of user."
                },
                "name": {
                    "type": "string",
                    "description": "Name of user."
                }
            },
            "required": [
                "id",
                "name"
            ]
        }
    }
}

When I try to run the apidoc-swagger command with my api I am getting the error
env: node\r: Not a directory
I am following the apidoc commands and have had apidoc working properly so I am not sure what the issue is. Any help would be great.

Given:

/**
 * @api {get} /user/id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

Build command:

apidoc-swagger -i app/ -o docs/

Produces:

"GetUser" : {
            "properties" : {
                "id" : {
                    "type" : "Number",
                    "description" : "<p>Users unique ID.</p> "
                },
                "firstname" : {
                    "type" : "String",
                    "description" : "<p>Firstname of the User.</p> "
                },
                "lastname" : {
                    "type" : "String",
                    "description" : "<p>Lastname of the User.</p> "
                }
            },
            "required" : ["id", "firstname", "lastname"]
        }

The "id" is an input parameter, but "firstname" and "lastname" is output parameters. All of them cannot be provided as the input parameters.

Please let me recommend to exclude node_modules folder from parsing (-e) by default, as apidoc-swagger tries to parse the third-party code therein and in most of the cases fails with the very unclear messages like error: Undefined error.

Now I can use apidoc to generate the html correctly.

But when I try to use command line to gen the swagger-ui json file like following:

apidoc-swagger -i router/ -o swagger_doc/

then I get the error like this :

'error: Cannot read property 'Parameter' of undefined'

It seems I have to debug from the apidoc-swagger source code?

Posted the issue on apidoc too but is there a way to define a param as a query param rather than a path?

By default any params seem to get set to be a path in apidoc.

apidoc-swagger doesn't run on Node.js 12 any more, it complains something about 'primordials':

fs.js:27
const { Math, Object } = primordials;
                         ^

ReferenceError: primordials is not defined
    at fs.js:27:26
    at req_ (/home/abix/.nvm/versions/node/v12.2.0/lib/node_modules/apidoc-swagger/node_modules/natives/index.js:143:24)
    at Object.req [as require] (/home/abix/.nvm/versions/node/v12.2.0/lib/node_modules/apidoc-swagger/node_modules/natives/index.js:55:10)
    at Object. (/home/abix/.nvm/versions/node/v12.2.0/lib/node_modules/apidoc-swagger/node_modules/graceful-fs/fs.js:1:37)
    at Module._compile (internal/modules/cjs/loader.js:759:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:770:10)
    at Module.load (internal/modules/cjs/loader.js:628:32)
    at Function.Module._load (internal/modules/cjs/loader.js:555:12)
    at Module.require (internal/modules/cjs/loader.js:666:19)
    at require (internal/modules/cjs/helpers.js:16:16)

Hi @fsbahman, thanks so much for this module. It just saved a lot time.

I had manually correct some data types, tho
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#dataTypeFormat

Eg.
apidoc-swagger output

prop:
  type: float
prop2:
  type: bigint
prop3:
  type: date

valid OpenAPI data type and format

prop:
  type: number
  format: float
prop2:
  type: integer
  format: int64
prop3:
  type: string
  format: date

It would be great to fix this. If I manage to have some time to work on this I'll make a PR.
Opening the issue for now.

I'm trying to use apidoc-swagger to convert apidoc project to swagger ui:

This is the result I'm getting after
$apidoc -i documentation/apis/rest -o documentation/generated/rest/ -f .adoc -v

verbose: apidoc-generator name: apidoc verbose: apidoc-generator version: 0.16.1 verbose: apidoc-core version: 0.7.1 verbose: apidoc-spec version: 0.2.0 verbose: run parser verbose: parse file: documentation/apis/rest/_apidoc.adoc verbose: parse file: documentation/apis/rest/errors.adoc verbose: parse file: documentation/apis/rest/parameters.adoc verbose: parse file: documentation/apis/rest/v1_0/EmailTemplatesLanguageRestController.adoc verbose: parse file: documentation/apis/rest/v1_0/EmailTemplatesRestController.adoc verbose: parse file: documentation/apis/rest/v1_0/FormsFieldsRestController.adoc verbose: parse file: documentation/apis/rest/v1_0/FormsRestController.adoc verbose: run worker verbose: worker preProcess: apierrorstructure verbose: worker preProcess: apierrortitle verbose: worker preProcess: apigroup verbose: worker preProcess: apiheaderstructure verbose: worker preProcess: apiheadertitle verbose: worker preProcess: apiparamtitle verbose: worker preProcess: apipermission verbose: worker preProcess: apistructure verbose: worker preProcess: apisuccessstructure verbose: worker preProcess: apisuccesstitle verbose: worker preProcess: apiuse verbose: worker postProcess: apierrorstructure verbose: worker postProcess: apierrortitle verbose: worker postProcess: apigroup verbose: worker postProcess: apiheaderstructure verbose: worker postProcess: apiheadertitle verbose: worker postProcess: apiname verbose: worker postProcess: apiparamtitle verbose: worker postProcess: apipermission verbose: worker postProcess: apisamplerequest verbose: worker postProcess: apistructure verbose: worker postProcess: apisuccessstructure verbose: worker postProcess: apisuccesstitle verbose: worker postProcess: apiuse verbose: run filter verbose: filter postFilter: apierror verbose: filter postFilter: apiheader verbose: filter postFilter: apiparam verbose: filter postFilter: apisuccess verbose: create dir: documentation/generated/rest/ verbose: copy template /usr/lib/node_modules/apidoc/template/ to: documentation/generated/rest/ verbose: write json file: documentation/generated/rest/api_data.json verbose: write js file: documentation/generated/rest/api_data.js verbose: write json file: documentation/generated/rest/api_project.json verbose: write js file: documentation/generated/rest/api_project.js info: Done.

And this is the result I get from
$apidoc-swagger -i documentation/apis/rest -o documentation/generated/rest/swagger -f .adoc -v

verbose: apidoc-generator name: apidoc-swagger verbose: apidoc-generator version: 0.2.2 verbose: apidoc-core version: 0.3.1 verbose: apidoc-spec version: 0.2.0 verbose: run parser verbose: parse file: documentation/apis/rest/_apidoc.adoc verbose: parse file: documentation/apis/rest/errors.adoc verbose: parse file: documentation/apis/rest/parameters.adoc verbose: parse file: documentation/apis/rest/v1_0/EmailTemplatesLanguageRestController.adoc verbose: parse file: documentation/apis/rest/v1_0/EmailTemplatesRestController.adoc verbose: parse file: documentation/apis/rest/v1_0/FormsFieldsRestController.adoc verbose: parse file: documentation/apis/rest/v1_0/FormsRestController.adoc verbose: run worker verbose: worker preProcess: apierrorstructure verbose: worker preProcess: apierrortitle verbose: worker preProcess: apigroup verbose: worker preProcess: apiheaderstructure verbose: worker preProcess: apiheadertitle verbose: worker preProcess: apiparamtitle verbose: worker preProcess: apipermission verbose: worker preProcess: apistructure verbose: worker preProcess: apisuccessstructure verbose: worker preProcess: apisuccesstitle verbose: worker preProcess: apiuse verbose: worker preProcess: deprecatedApiErrorTitle verbose: worker preProcess: deprecatedApiHeaderTitle verbose: worker preProcess: deprecatedApiParamTitle verbose: worker preProcess: deprecatedApiSuccessTitle verbose: worker postProcess: apierrorstructure verbose: worker postProcess: apierrortitle verbose: worker postProcess: apigroup verbose: worker postProcess: apiheaderstructure verbose: worker postProcess: apiheadertitle verbose: worker postProcess: apiname verbose: worker postProcess: apiparamtitle verbose: worker postProcess: apipermission verbose: worker postProcess: apisamplerequest verbose: worker postProcess: apistructure verbose: worker postProcess: apisuccessstructure verbose: worker postProcess: apisuccesstitle verbose: worker postProcess: apiuse verbose: worker postProcess: deprecatedApiErrorTitle verbose: worker postProcess: deprecatedApiHeaderTitle verbose: worker postProcess: deprecatedApiParamTitle verbose: worker postProcess: deprecatedApiSuccessTitle verbose: run filter verbose: filter postFilter: apierror verbose: filter postFilter: apiheader verbose: filter postFilter: apiparam verbose: filter postFilter: apisuccess error: Cannot read property 'length' of undefined

Any idea on how can I fix this issue, or how can I investigate more?

http://apidocjs.com/#param-api-param

For example:

@apiParam {Number} [age=18] Optional Age with default 18.

The default value shows up as 0 when generating swagger.json. When generating doc with api-doc, the default shows up as 18.

I'm using apidoc-swagger against a project which annotates URL parameters using a group named "URL Parameters" instead of the default, and I ran across some unsafe access patterns to the Parameters array.

Specifically,var required = verbs.parameter && verbs.parameter.fields && verbs.parameter.fields.Parameter.length > 0; on line 83 of apidocToSwagger.js makes an unsafe check, which causes an unhandled exception if "Parameter" is not defined.

PR incoming.

Hello,

When I use the tool to generate swagger docs for a GET method, it creates a definition for the input but doesn't use it. This causes a warning when copying the text into the swagger editor and adds some un-needed cruft to the swagger.json.

For example, here is a sample comment string I'm using.

/**
     * @api {get} /store/{storeId}/States/StatesForCountry?countryCode={countryCode}
     * @apiName getStatesForCountry
     * @apiDescription For a given store and country, returns the list of states/provinces
     * @apiGroup Group
     * 
     * @apiParam {String} storeId store id
     * @apiParam {String} countryCode country code
     * 
     * @apiSuccess {Array} getStatesForCountryResponse A list of objects containing state information
     * @apiSuccess {String} getStatesForCountryResponse.code The 2 letter state code
     * @apiSuccess {String} getStatesForCountryResponse.displayName The full display name of the state
     * 
     * @apiError (500) Internal server error
     */

The output swagger has an erroneous getStatesForCountry definition.

apidoc on it's own runs smoothly.

apidoc-swagger -i dist/ -o doc/
(node:10252) fs: re-evaluating native module sources is not supported. If you are using the graceful-fs module, please update it to a more recent version.
warn: parser plugin 'param' not found in block: 0
error: Cannot read property 'indexOf' of undefined

Currently, I don't see apidoc-swagger able to parse Object[] and recognizing 4xx error codes.
But latest apidoc is supporting that. Is there a plan for apidoc-swagger to support the latest version of apidoc?

Where should the swagger json file be appearing in our folder? I am not seeing it, just want to make sure I get the right idea and am able to be successful with it. Any help would be great.

Hi there,

would it be possible to support latest OpenAPI 3.0.x specifications https://swagger.io/specification/ ?

hello, I hope this is a bug.
var matches = pattern.exec(url);
and we want to use the matches.length but sometimes we got a null because the matches hasn't lenght.
If you have time please check this in apidocToSwagger.js file.

so I corrected myself locally:
if(matches) {
for (var j = 1; j < matches.length; j++) {
var key = matches[j].substr(1);
url = url.replace(matches[j], "{" + key + "}");
pathKeys.push(key);
}
}

Cannot target specific files, it generates .json only for the last file in the range e.g.:
apidoc-swagger -f './app/example.ts' -f './app/example_2.ts' -o ../doc

we will see only docs for example_2.ts, is this supported?

I'd like to combine the power of the apiDoc with Swagger's excellent api-tools such as the swagger-node-runner but there are some issues when I try converting even the basic hello-world example. For Swagger to properly function it needs:

1. x-swagger-router-controller - the name of the controller js-file where the function is located
2. operationId - the name of the function that is executed (probably the same as the @apiName)
3. @apiError seems to be ignored

In addition there are strange definitions that I have no idea where they come from.

Setup of a Swagger hello-world project with apiDoc

I've created a project via the standard Swagger-tools removed the swagger.yaml and recreated the docs via apidoc-swagger that was then converted into yaml using json2yaml, here's the core script to create the project:

npm install -g swagger
swagger project create hello-world
cd hello-world
mv api/swagger/swagger.yaml api/swagger/swagger_org.yaml

# Edit the api/controller/hello_world.js before this:
apidoc-swagger -i api/ -o api/swagger/ && json2yaml ./api/swagger/swagger.json  > ./api/swagger/swagger.yaml

The /api/controller/hello_world.js now contains something like this:

'use strict';
var util = require('util');

module.exports = {
  hello: hello
};

/**
 * @apiDefine ErrorResponse
 *
 * @apiError BasicErrorResponse Server fail
 */

/**
 * @apiDefine SuccessResponse
 *
 * @apiSuccess {String} A string with "Hello, {name}" where name is stranger if omitted
 */

/**
 * @api {get} /hello
 * @apiName hello
 * @apiGroup main
 *
 * @apiDescription Returns 'Hello' to the caller
 *
 * @apiParam {String} [name] The name of the person to whom to say hello
 *
 * @apiUse SuccessResponse
 * @apiUse ErrorResponse
 */
function hello(req, res) {
  // variables defined in the Swagger document can be referenced using req.swagger.params.{parameter_name}
  var name = req.swagger.params.name.value || 'stranger';
  var hello = util.format('Hello, %s!', name);

  // this sends back a JSON response which is a single string
  res.json(hello);
}

I also have a simple apidoc.json under /api/:

{
  "name": "Hello world example",
  "version": "1.0",
  "description": "apiDoc hello world example based upon the `swagger project create hello_world`"
}

The generated Swagger yaml file:

Worth noting is also the odd definitions that appear at the end. I've tried without the @apiUse but it doesn't change.

---
  swagger: "2.0"
  info: 
    title: "Hello world example"
    version: "1.0"
    description: "apiDoc hello world example based upon the `swagger project create hello_world`"
  paths: 
    /hello: 
      get: 
        tags: 
          - "main"
        summary: "Returns 'Hello' to the caller "
        consumes: 
          - "application/json"
        produces: 
          - "application/json"
        parameters: 
          - 
            name: "name"
            in: "path"
            required: false
            type: "string"
            description: "The name of the person to whom to say hello "
        responses: 
          200: 
            description: "successful operation"
            schema: 
              type: "String"
              items: 
                $ref: "#/definitions/hello"
  definitions: 
    hello: 
      properties: 
        name: 
          type: "string"
          description: "The name of the person to whom to say hello "
        A: 
          type: "string"
          description: "string with "Hello, {name}" where name is stranger if omitted "
      required: 
        - "A"

The original swagger.yaml

Here's the swagger_org.yaml file that I stashed away in the beginning:

swagger: "2.0"
info:
  version: "0.0.1"
  title: Hello World App
# during dev, should point to your local machine
host: localhost:10010
# basePath prefixes all resource paths 
basePath: /
# 
schemes:
  # tip: remove http to make production-grade
  - http
  - https
# format of bodies a client can send (Content-Type)
consumes:
  - application/json
# format of the responses to the client (Accepts)
produces:
  - application/json
paths:
  /hello:
    # binds a127 app logic to a route
    x-swagger-router-controller: hello_world
    get:
      description: Returns 'Hello' to the caller
      # used as the method name of the controller
      operationId: hello
      parameters:
        - name: name
          in: query
          description: The name of the person to whom to say hello
          required: false
          type: string
      responses:
        "200":
          description: Success
          schema:
            # a pointer to a definition
            $ref: "#/definitions/HelloWorldResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /swagger:
    x-swagger-pipe: swagger_raw
# complex objects have schema definitions
definitions:
  HelloWorldResponse:
    required:
      - message
    properties:
      message:
        type: string
  ErrorResponse:
    required:
      - message
    properties:
      message:
        type: string

When there are no parameters for an API call it gives an invalid reference to null in the schema

e.g./api/v1/licenses/list with no parameters produced

		"/api/v1/licenses/list": {
			"post": {
				"tags": ["Licenses"],
				"summary": "Shows all licenses that can be applied for. ",
				"consumes": ["application/json"],
				"produces": ["application/json"],
				"parameters": [{
					"in": "body",
					"name": "body",
					"description": "Shows all licenses that can be applied for. ",
					"schema": { "$ref" : "#/definitions/null"}
				}],

i.e. the post.parameters[0].schema.$ref is pointing at #/definitions/null"
This causes swagger to complain when running

See title.

I myself fixed the "multiple methods under one path" issue... only to find out, that it has already been fixed in the current master.

Please release a fresh version to npm. Thanks.

Example apidoc:

/**
 * @api {post} /stuff Create a new stuff
 * @apiName createStuff
 * @apiGroup createStuffGroup
 *
 * @apiSampleRequest http://localhost:17443/stuff
 *
 * @apiParamExample {json} Post-Example: set stuff
 *    {
 *       "name": "stuff"
 *    }
 *
 */

Causes this issue:
error: Cannot read property 'Parameter' of undefined
debug: TypeError: Cannot read property 'Parameter' of undefined
at createPathParameters (/stuff/node_modules/apidoc-swagger/lib/apidocToSwagger.js:275:45)
at createPostPushPutOutput (/stuff/node_modules/apidoc-swagger/lib/apidocToSwagger.js:76:19)
at extractPaths (/stuff/node_modules/apidoc-swagger/lib/apidocToSwagger.js:62:19)
at Object.toSwagger (/stuff/node_modules/apidoc-swagger/lib/apidocToSwagger.js:13:18)
at Object.createApidocSwagger (/stuff/node_modules/apidoc-swagger/lib/index.js:107:63)
at Object. (/stuff/node_modules/apidoc-swagger/bin/apidocSwagger.js:143:19)
at Module._compile (module.js:409:26)
at Object.Module._extensions..js (module.js:416:10)
at Module.load (module.js:343:32)
at Function.Module._load (module.js:300:12)

Please update apidoc-core & lodash in your package.json to latest!

...
"dependencies": {
    "apidoc-core": "0.3.1",
    "fs-extra": "^0.16.5",
    "lodash": "^3.5.0",
    "marked": "^0.3.3",
    "nomnom": "^1.8.1",
    "path-to-regexp": "^1.2.0",
    "winston": "^0.9.0"
},
...

npm audit on this project reports:

$ npm audit

                       === npm audit security report ===

┌──────────────────────────────────────────────────────────────────────────────┐
│                                Manual Review                                 │
│            Some vulnerabilities require your attention to resolve            │
│                                                                              │
│         Visit https://go.npm.me/audit-guide for additional guidance          │
└──────────────────────────────────────────────────────────────────────────────┘
┌───────────────┬──────────────────────────────────────────────────────────────┐
│ Low           │ Prototype Pollution                                          │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Package       │ lodash                                                       │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Patched in    │ >=4.17.5                                                     │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Dependency of │ apidoc-swagger                                               │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Path          │ apidoc-swagger > apidoc-core > lodash                        │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ More info     │ https://nodesecurity.io/advisories/577                       │
└───────────────┴──────────────────────────────────────────────────────────────┘
┌───────────────┬──────────────────────────────────────────────────────────────┐
│ Low           │ Prototype Pollution                                          │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Package       │ lodash                                                       │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Patched in    │ >=4.17.5                                                     │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Dependency of │ apidoc-swagger                                               │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Path          │ apidoc-swagger > lodash                                      │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ More info     │ https://nodesecurity.io/advisories/577                       │
└───────────────┴──────────────────────────────────────────────────────────────┘
┌───────────────┬──────────────────────────────────────────────────────────────┐
│ Moderate      │ Regular Expression Denial of Service                         │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Package       │ semver                                                       │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Patched in    │ >=4.3.2                                                      │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Dependency of │ apidoc-swagger                                               │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Path          │ apidoc-swagger > apidoc-core > semver                        │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ More info     │ https://nodesecurity.io/advisories/31                        │
└───────────────┴──────────────────────────────────────────────────────────────┘
found 3 vulnerabilities (2 low, 1 moderate) in 1034 scanned packages
  3 vulnerabilities require manual review. See the full report for details.