Membangun server dokumentasi mandiri di Node.JS

Kondisi:

• validasi melalui Joi

  
  
  
  
  

• menggunakan Ketikan

  
  
  
  
  

• Server ekspres

  
  
  
  
  

• SWAGGER di / api-docs

  
  
  
  
  

Tugas: KERING

Keputusan:

Pertama, Anda perlu memutuskan apa yang lebih dulu: skema Joi, Swagger atau antarmuka TypeScript. Telah ditetapkan secara empiris bahwa Joi harus dijadikan yang utama.

1. Menginstal semua modul di Express

npm install --save swagger-ui-express
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Tambahkan baris ke app.ts (index.ts):

import swaggerUI = require('swagger-ui-express')
import swDocument from './openapi'
...
app.use('/api-docs',swaggerUI.serve,swaggerUI.setup(swDocument))

      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

2. Buat ./openapi.ts

. ( , ) SWAGGER-. openapi v3.0.0

:

import {swLoginRoute} from './routes/login'

const swagger = {
  openapi: '3.0.0',
  info: {
    title: 'Express API for Dangle',
    version: '1.0.0',
    description: 'The REST API for Dangle Panel service'
  },
  servers: [
    {
      url: 'http://localhost:3001',
      description: 'Development server'
    }
  ],
  paths: {
    ...swLoginRoute
  },
}

export default swagger
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

.

3.

openapi-

./routes/login/index.ts:

import {swGetUserInfo} from './get-user-info'
import {swUpdateInfo} from './update-info'
export const swLoginRoute = {
  "/login": {
    "get": {
      ...swGetUserInfo
    },
    "patch": {
      ...swUpdateInfo
    }
  }
}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

/login, : get patch. get-user-into.ts update-info.ts. .

4.

, Joi-.

.

: , .

update-info.ts, ( ):

import schema, {joiSchema} from './update-info.spec/schema'

export const swUpdateInfo = {
  "summary": "update the user info",
  "tags": [
    "login"
  ],
  "parameters": [
    {
      "name": "key",
      "in": "header",
      "schema": {
        "type": "string"
      },
      "required": true
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          ...schema
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Done"
    },
    "default": {
      "description": "Error message"
    }
  }
}
// ...   

      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

JSON- Swagger-, . :

"schema": {
  ...schema
}

      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

.

Joi- :

await joiSchema.validateAsync(req.body)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

4. Joi-

Joi:

npm install --save joi joi-to-swagger
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

:

const joi = require('joi')
const j2s = require('joi-to-swagger')

// Joi
export const joiSchema = joi.object().keys({
  mode:    joi.string().required(),
  email:   joi.string().email()
})
// end of Joi

const schema = j2s(joiSchema).swagger
export default schema

      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Joi- swagger-.

, SWAGGER- . TypeScript-

5. TypeScript

npm install --save-dev gulp @babel/register @babel/plugin-proposal-class-properties @babel/preset-env @babel/preset-typescript
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Gulp. , . gulpfile.ts :

const gulp = require('gulp')
const through = require('through2')
import { compile } from 'json-schema-to-typescript'
const fs = require('fs')

const endName = "schema.ts"
const routes = `./routes/**/*.spec/*${endName}`

function path(str: string) : string
{
   let base = str
   if(base.lastIndexOf(endName) != -1)
     base = base.substring(0, base.lastIndexOf(endName))
   return base
}

gulp.task('schema', () => {
  return gulp.src(routes)
    .pipe(through.obj((chunk, enc, cb) => {
      const filename = chunk.path
      import(filename).then(schema => { // dynamic import
        console.log('Converting', filename)
        compile(schema.default, `IDTO`)
          .then(ts => {
            //console.log(path(filename).concat('interface.ts'), ts)
            fs.writeFileSync(path(filename).concat('interface.ts'), ts)
          })
        })
      cb(null, chunk)
    }))
})


// watch service
const { watch, series } = require('gulp')
exports.default = function() {
  watch(routes, series('schema'))
}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Skrip melewati semua subdirektori bernama * .spec di dalam direktori dari router. Di sana ia mencari file dengan nama * schema.ts dan membuat sejumlah file dengan nama * interface.ts

Kesimpulan

Tentu saja, objek JSON yang besar dan kompleks dengan spesifikasi openAPI ini menakutkan, tetapi Anda perlu memahami bahwa objek tersebut tidak ditulis secara manual, tetapi dihasilkan oleh utilitas SWAGGER.

Karena kurangnya pengalaman, penyesuaian awal mekanisme dapat memakan waktu lama, tetapi ini akan menghemat ratusan jam yang dapat dihabiskan untuk rutinitas!