Before there was a project, the leader said that I used mongoose to swagger to write down the back-end interface. Although I had not written the back-end interface before, I wanted to have colleagues and accepted the work happily. First to ask colleagues, and then... Have not used; so Baidu to see if there is a relevant tutorial 😭 , well, it's up to me

Maybe write down the interface

• Some processing in the main file

  const m2s = require('mongoose-to-swagger');
  module.exports = function (app) {
      var swaggerJSDoc = require('swagger-jsdoc');
      var swaggerSpec = swaggerJSDoc({
          swaggerDefinition: {
              info: {
                  title: 'Web API',
                  version: '1.0.0',
                  description: 'Demonstrating how to describe a RESTful API with Swagger',
              },
              host: 'localhost:2000',
              basePath: '/'
          },
          apis: ['./controller/*.js'],//Location of interface documents
      });
      //Note: user module is introduced and used here, which is convenient for later interface writing
      var user = require('./model/account/user');
      swaggerSpec.definitions = {
          user: m2s(user), role: m2s(role),
      };
  
      app.get('/swagger.json', function (req, res) {
          res.setHeader('Content-Type', 'application/json');
          res.send(swaggerSpec);
      });
  }
  
  
  

Users in it

const mongoose = require('mongoose');
const addressSchema = require("../schema/addressSchema");//Reference other models
const Schema = mongoose.Schema;

//age phone file
const userSchema = new Schema({
  username: { type: String, unique: true },
  password: { type: String},
  nickname: String,
  token: String,
  gender: String,
  address: addressSchema,//Define as other model
  photo: String,
  created_date: { type: Date, default: Date.now },
}, { collection: 'user' });

//Query users by username
userSchema.static('findByUserName', function(username) {
  return this.find({ username });
});

const UserModel = mongoose.model('user', userSchema);
module.exports = UserModel;

• Interface writing

Because I haven't written the interface before, I thought I could generate the swagger interface

  app.post("/user/create", async function (req, res) {}

Of course, I'm wrong. This interface is generated by annotation (at least in swift, /... / when it is written in this way).

  /**
  * @swagger
  */ api/user/login: (corresponding to the lower interface)
  *   post:
  *     tags:
  *       - User
  *summary: login (interface description)
  *     produces:
  *       - application/json
  *parameters: (parameter related)
  *- name: body (parameter name)
  *Description: parameter (description of the parameter)
  *in: body
  *required: true (required or not)
  *         schema:
  *           title: login
  *           properties:
  *             username:
  *type: string (type integer, boolean, etc.)
  *Description: nickname (description)
  *Default: nickname (default)
  *             password:
  *               type: string
  *description: password
  *default: password
  *Required: (you can check whether it is a required item in the incoming model. Only the prompt given by the user, the real processing logic still needs to be processed in the interface.)
  *             - username
  *responses: (return data related)
  *       200:
  *         description: Successfully
  *         schema:
  *$Ref: 'ා / definitions / user' (directly use the user model referenced in the main page, which can also be done in parameters to avoid writing one by one)
  */
   app.post('/user/login', function (req, res) {... I will not write the logic in...}

The space distance between the right side and * will be related to its nodes. Please note

The following figure is the generated interface. You can have a comparative look at it

• Let's get another parameter in query

    /**
    * @swagger
    * /api/user/login:
    *   get:
    *     tags:
    *       - User
    *     summary: Sign in
    *     produces:
    *       - application/json
    *     parameters:
    *       - name: username
    *         description: Nickname?
    *         in: query
    *         required: true
    *         type: string
    *       - name: password
    *         description: password
    *         in: query
    *         required: false
    *         type: string
    *     responses:
    *       200:
    *         description: Successfully
    *         schema:
    *           $ref: '#/definitions/user'
    */
    app.get('/user/login', function (req, res) {...}
  

  Again, the following is the interface

Anyway, at least it's coming out