swagger-api / swagger-api/swagger-ui

How to introduce a large JSON data file inside the "example" field in NodeJS ?

Open
#8,347 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Versions
  • OS: [windows]
  • Browser: [brave]
  • Version: [1.47.171]
  • Method of installation: [npm]
  • Swagger-UI version: [^4.3.0]
  • Swagger/OpenAPI version: [OpenAPI 3.0]
  • Swagger-jsdoc: "^6.2.5",
  • Swagger-ui-express: "^4.3.0",
A variable in an example

in case these is not the correct place to these question please help to find the correct one.

I have these JSON file with raw_data and i need to introduce it as a variable in the example. The problem i'm encountering is that because the swagger code is in commented lines. Swagger is rendering the example variable as a string and not counting on the
raw_data i need to introduce. I'd tried so many things and i'm not reaching to find the solution.

things i tried :

  • example: phonationPayloadParsed.raw_data
  • example: phonationPayloadParsed.raw_data
  • example: $ref: phonationPayloadParsed.raw_data
  • example: $ref: $(phonationPayloadParsed.raw_data)
  • example: $ref:${JSON.stringify(phonationPayloadParsed)}

With the $ref and without, with backtic and without..

Is there a possible way ?
Should i configure something in swagger.
is these question already asked and i didn't found it in google ?
i did the same question on stackoverflow in case you have a hint and you want some point as reward: https://stackoverflow.com/questions/75135343/how-to-use-a-variable-in-swagger-ui-commented-code-style-in-nodejs?noredirect=1#comment132590656_75135343

image

Swagger-UI configuration options:


import express from "express";
import authenticateToken from "../../../middleware/auth.js";
import { postPythonFeatures } from "../../../utils/python-requests.js";
import phonationValidator from "./validator.js";
import { addPhonation, getBy_phonationId } from "./functions.js";

const router = express.Router();

//Payload Here is the JSON file in question
import fs from "fs";
import path from "path";
const phonationDataPath = path.resolve("src/routes/data/phonation/phonationData.json");
const phonationPayload = fs.readFileSync(phonationDataPath);
const phonationPayloadParsed = JSON.parse(phonationPayload);


/**
 * @swagger
 * /data/phonation:
 *   post:
 *
 *     security:
 *     -  bearerAuth: []
 *
 *     summary: Add Phonation
 *     description: Please remember that i didn't insert all raw_data in the example so your score will be null.<br><br> - [Reminder] Score calculation -> (model_v3_corr_4s_5 + model_v3_corr_4s_10)*2 <- From phonation_features (inserted by Python)
 *     tags: [data/ Phonation]
 *
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/Phonation'
 *     responses:
 *       200:
 *         description: successful operation
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/inner/PhonationResPOST'
 *       400:
 *         description: validation Fail /or/ Unexpected token, in JSON at position 108
 *       401:
 *         description: No token, authorization denied
 */

//! Schema POST
/**
 * @swagger
 * components:
 *   schemas:
 *      Phonation:
 *
 *       type: object
 *
 *       required:
 *         - date
 *         - status
 *         - raw_data
 *
 *       properties:
 *
 *         date:
 *           type: string
 *           timestamp-format: yyyy-MM-dd HH:mm:ss
 *           example: "2022-09-21 14:56:15"
 *
 *         status:
 *           type: integer
 *           example: 3
 *
 *         raw_data:
 *           type: string
 *           format: binary
 *           example: $ref:`${JSON.stringify(phonationPayloadParsed.raw_data)}`
 */

// these is the example i need to  add my JSON data ↑↑↑  phonationPayloadParsed.raw_data 

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the JSDoc schema for Phonation and src/routes/data/phonation/phonationData.json, then inspect how the generated OpenAPI document represents raw_data.example and $ref. Compare the documented OpenAPI example rules with Swagger UI's rendering behavior. Done should be a confirmed supported approach or a clearly documented limitation.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, node.js, openapi
Domain
api, documentation
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.