11

I am currently using ajv to validate some API inputs in node/express. The expected data is described in a .json schema file.

Now I would like to re-use this file to document my API, relying on swagger-ui-express and swagger-jsdoc.

There are quite many references to how to re-use an object definition in swagger, but all these descriptions suppose that definition is given in a "@swagger" comment block.

I simply don't see how to point to a local JSON file.

If my comment is shaped like this:

/**
* @swagger
* /init/user:
*   post:
*     description: Creates a user
*     produces:
*       - application/json
*     parameters:
*       - in: body
*         name: create user
*         required: true
*         schema:
*           $ref: 'schemas/initUserApi.json'
*/

(note this is an incomplete template, I want to focus on the problem), then the ultimate swagger output will throw an error:

Could not resolve reference: Tried to resolve a relative URL, without having a basePath. path: 'schemas/initUserApi.json' basePath: 'undefined'

I tried defining a 'components' section as described in this issue: Cannot reference a component schema defined in a separate file in Swagger, this does nothing.

I tried using absolute/relative file names, etc (also another suggestion here: How to use $ref in swagger file properly while working with swagger-ui-express and swagger-jsdoc), to no avail.

Is this possible? The goal is really to use a separate json file as a schema, as I would like to have a single source of information. I am not clear on how the swagger-ui-express/swagger-jsdoc chain works, would this json file need somehow to be served by my swagger web server (this is really for documentation running on localhost for now, no public/intranet publishing) ?

Will59
  • 1,430
  • 1
  • 16
  • 37

1 Answers1

0

it’s a bit old but for all those who are still looking for the solution it seems to me that this one works.

First, you have to export your schema from your json file as such:

export const initUserApi = {
  type: 'object',
  properties: {...}
};

Then, in the file where your swagger configuration is located, you have to add this schema to your Schemas, inside your swagger Components:

/**
 * @swagger
 * infos: ...
 * basepath: ...
 * paths: ...
 * components:
 *   schemas:
 *     initUserApi:
 *       $ref: 'path/to/initUserApi.json'
 */

Once it’s done, you can use this new initUserApi schema with your routes as such:

/**
* @swagger
* /init/user:
*   post:
*     description: Creates a user
*     produces:
*       - application/json
*     parameters:
*       - in: body
*         name: create user
*         required: true
*         schema:
*           $ref: '#/components/schemas/initUserApi'
*/

But depending on your swagger/openapi version (2.0, 3.0.n, 3.1, etc...), this solution may not work, so you will probably have to convert your JSON file to YAML file. There is a bunch of online converters for this, the most easiest and most convenient being this one, which I often use: https://www.json2yaml.com/

Then it should normally work.

Maxime Warluzel
  • 1
  • 2