Some problems of writing interface with mongoose to swagger

Keywords: Mobile Mongoose JSON Swift

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

Posted by Gorillas on Thu, 11 Jun 2020 22:56:59 -0700