support multiple tags as an array and in definition

[efmr]

Allow to set multiple tags in jsdoc with as an array
It will allow definition of tags in swagger definition and will merge with others in the jsdoc.

[drGrove]

Does this support yaml array syntax?

[efmr]

@drGrove Yes it does.

[drGrove]

@efmr, would you mind writing a test for this so we make sure that we don't get a regression in the future?

[efmr]

@drGrove Alright, just did it ce6a493 .

[drGrove]

Thanks @efmr, I'll merge this tonight unless @chdanielmueller says otherwise.

[chdanielmueller]

@drGrove fine with me

[cguedes]

Hi. First, great work here. This project is very nice.

I've noticed that you are using tag instead of tags in the examples for operations (https://github.com/Surnet/swagger-jsdoc/blob/2ea4993ace5cc268428666a9119b09e21585e3a9/example/routes.js#L55).
Check the Operation Object of swagger spec to see that we should use tags instead.

[kalinchernev]

Hi @cguedes, I looked now at the "Operation Object of swagger spec" link, yes, you're correctly pointing out that the final output has to have the tags property (plural)
There's an open issue #33 which is related, and as far as i see it's outputting a plural for of a property.
Do you comment only about the examples files? In also about the implementation?

[cguedes]

TLDR: I'm talking about example files.

There are two places where tags are defined in the swagger spec. The list of all tags:

1. In the field tags at the root of the spec

    info: {
      'title': 'Hello Word',
      'description': 'This is a sample server Petstore server.',
    },
    tags:[
      {
        'name': 'user',
        'description': 'User APIs'
      },
      {
        'name': 'setting',
        'description': 'Setting APIs'
      }
    ],
    basePath: '/api'
  }

This is ok.

2. In the operation object that is "A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier." of type [string].

This second should be defined per API using JSDOC with the following:

  /**
   * @swagger
   * /login:
   *   post:
   *     description: Login to the application
   *     tags: [Users, Login]
   *     produces:
   *       - application/json
   */

instead of

  /**
   * @swagger
   * /login:
   *   post:
   *     description: Login to the application
   *     tag: [Users, Login]
   *     produces:
   *       - application/json
   */

At the moment you are not validating this, so people can change, but following the example they may end up with issues regarding this change (like myself).

[efmr]

I suggest you create a separate issue on this subject. There is definitely a point to keeping the jsdoc as similar as possible to the specification it produces.

Wouldn't this also apply to other properties such as response and parameter? Check: https://github.com/Surnet/swagger-jsdoc/blob/master/lib/index.js#L105.

[kalinchernev]

@cguedes thanks a lot of the details, I linked them in the issue
@efmr makes sense indeed, I'll have look to having validations on the specification-specific :) properties
Thanks for the input!