The swagger-node-runner requires additional elements for proper conversion

[gforge]

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

[sp90]

Any solution to this

[LiorArbel]

It would be amazing for my team if this could be fixed