Swagger - добавить статический необязательный сегмент подпути в документации

Я пытаюсь задокументировать свой API с помощью чванства.
У меня есть базовая конечная точка для /api/quotes, которая возвращает все кавычки в коллекции, и еще одна для api/quotes/random, где возвращается одна случайная цитата.

Чтобы никого не запутать, у меня также есть возможность передать параметр запроса /api/quotes?random=true для рандомизации порядка коллекции. Этот работает, как ожидалось.

Я задокументировал первую конечную точку с помощью jsDoc / yaml

/**
 * @swagger
 * /api/quotes/:
 *   get:
 *     tags:
 *       - Greek mythological Quotes
 *     description: get mythological quotes
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: random
 *         in: query
 *         description: "Optional param to randomize list order"
 *         type: boolean
 *     responses:
 *       200:
 *         description: list of all mythological quotes
 *         schema:
 *           $ref: '#/definitions/Quote'
 */

Пока что у меня есть это. Как я могу добавить в эту документацию необязательный подпуть / случайный путь?
Как я могу сгруппировать эти конечные точки в swagger?
Это успокаивает?


rest endpoint swagger
person Kevin Amiranoff    schedule 07.01.2017    source источник

Ответы (1)


arrow_upward
0
arrow_downward

На самом деле чванство сделало это для меня автоматически. Я только что добавил:

/**
 * @swagger
 * /api/quotes/random:
 *   get:
 *     tags:
 *       - Greek mythological Quotes
 *     description: Fetch one random mythological quote
 *     produces:
 *       - application/json
 *     responses:
 *       200:
 *         description: One random mythological quote
 *         schema:
 *           $ref: '#/definitions/Quote'
 */

И чванству удалось сгруппировать маршруты. введите здесь описание изображения

Я до сих пор задаюсь вопросом, НАСЛАЖДАЕТСЯ ли это ...

person Kevin Amiranoff    schedule 09.01.2017