add tags.list, tags.search API reference

src/server/routes/page.js

@@ -126,14 +126,6 @@
  *            type: string
  *            description: date created at
  *            example: 2010-01-01T00:00:00.000Z
- *
- *      Tags:
- *        description: Tags
- *        type: array
- *        items:
- *          type: string
- *          description: tag name
- *        example: ['daily', 'report', 'tips']
  */
 
 /* eslint-disable no-use-before-define */
@@ -669,6 +661,10 @@ module.exports = function(crowi, app) {
    *            schema:
    *              $ref: '#/components/schemas/User/properties/username'
    *          - in: query
+   *            name: limit
+   *            schema:
+   *              $ref: '#/components/schemas/V1PaginateResult/properties/meta/properties/limit'
+   *          - in: query
    *            name: offset
    *            schema:
    *              $ref: '#/components/schemas/V1PaginateResult/properties/meta/properties/offset'

src/server/routes/tag.js

@@ -1,3 +1,32 @@
+/**
+ * @swagger
+ *
+ *  components:
+ *    schemas:
+ *      Tags:
+ *        description: Tags
+ *        type: array
+ *        items:
+ *          $ref: '#/components/schemas/Tag/properties/name'
+ *        example: ['daily', 'report', 'tips']
+ *
+ *      Tag:
+ *        description: Tag
+ *        type: object
+ *        properties:
+ *          _id:
+ *            type: string
+ *            description: tag ID
+ *            example: 5e2d6aede35da4004ef7e0b7
+ *          name:
+ *            type: string
+ *            description: tag name
+ *            example: daily
+ *          count:
+ *            type: number
+ *            description: Count of tagged pages
+ *            example: 3
+ */
 module.exports = function(crowi, app) {
 
   const Tag = crowi.model('Tag');
@@ -12,6 +41,35 @@ module.exports = function(crowi, app) {
     return res.render('tags');
   };
 
+  /**
+   * @swagger
+   *
+   *    /_api/tags.search:
+   *      get:
+   *        tags: [Tags]
+   *        operationId: searchTags
+   *        summary: /_api/tags.search
+   *        description: Search tags
+   *        parameters:
+   *          - in: query
+   *            name: q
+   *            description: keyword to search
+   *        responses:
+   *          200:
+   *            description: Succeeded to tag list.
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  properties:
+   *                    ok:
+   *                      $ref: '#/components/schemas/V1Response/properties/ok'
+   *                    tags:
+   *                      $ref: '#/components/schemas/Tags'
+   *          403:
+   *            $ref: '#/components/responses/403'
+   *          500:
+   *            $ref: '#/components/responses/500'
+   */
   /**
    * @api {get} /tags.search search tags
    * @apiName SearchTag
@@ -55,6 +113,42 @@ module.exports = function(crowi, app) {
     return res.json(ApiResponse.success(result));
   };
 
+  /**
+   * @swagger
+   *
+   *    /_api/tags.list:
+   *      get:
+   *        tags: [Tags]
+   *        operationId: listTags
+   *        summary: /_api/tags.list
+   *        description: Get tags
+   *        parameters:
+   *          - in: query
+   *            name: limit
+   *            schema:
+   *              $ref: '#/components/schemas/V1PaginateResult/properties/meta/properties/limit'
+   *          - in: query
+   *            name: offset
+   *            schema:
+   *              $ref: '#/components/schemas/V1PaginateResult/properties/meta/properties/offset'
+   *        responses:
+   *          200:
+   *            description: Succeeded to tag list.
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  properties:
+   *                    ok:
+   *                      $ref: '#/components/schemas/V1Response/properties/ok'
+   *                    data:
+   *                      type: array
+   *                      items:
+   *                        $ref: '#/components/schemas/Tag'
+   *          403:
+   *            $ref: '#/components/responses/403'
+   *          500:
+   *            $ref: '#/components/responses/500'
+   */
   /**
    * @api {get} /tags.list get tagnames and count pages relate each tag
    * @apiName tagList