Skip to content
This repository has been archived by the owner on Jun 11, 2024. It is now read-only.

Allow use of @apiUse in @apiSuccessExmample & @apiErrorExample #1433

Open
IVoyt opened this issue Oct 6, 2023 · 1 comment
Open

Allow use of @apiUse in @apiSuccessExmample & @apiErrorExample #1433

IVoyt opened this issue Oct 6, 2023 · 1 comment

Comments

@IVoyt
Copy link

IVoyt commented Oct 6, 2023

Feature request

Please add possibility to specify @APIuse as body of @apiSuccessEample and @apiErrorExample section to make api documenting more flexible

Why this is needed.

For example we have multiple endpoints with same response body but different response codes.
The following would allow to get rid of duplication

Currently we have write as follows

/**
 * @api {get} /some-route
 * @apiGroup Some Group
 * 
 * @apiSuccessExample {json} Response-Example:
 * HTTP/1.1 200 OK
 * {
 *     "data": {
 *       // data body
 *     }
 * }
 */

/**
 * @api {post} /some-route
 * @apiGroup Some Group
 * 
 * @apiSuccessExample {json} Response-Example:
 * HTTP/1.1 201 Created
 * {
 *     "data": {
 *       // data body
 *     }
 * }
 */

My proposal is to allow write as follows

/**
 * @api {get} /some-route
 * @apiGroup Some Group
 * 
 * @apiSuccessExample {json} Response-Example:
 * HTTP/1.1 200 OK
 * @apiUse responseExample
 */

/**
 * @api {get} /some-route
 * @apiGroup Some Group
 * 
 * @apiSuccessExample {json} Response-Example:
 * HTTP/1.1 201 Created
 * @apiUse responseExample
 */

/**
 * @apiDefine responseExample
 *
 * {
 *     "data": {
 *       // data body
 *     }
 * }
 *
@NicolasCARPi
Copy link
Contributor

Hello,

Please take into account that there is nobody available to maintain this library. See #1436.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@NicolasCARPi @IVoyt