ดาวน์โหลด swagger ui express - swagger ui express Source Source Download

Swagger UI Express

งบ	กิ่งก้าน	ฟังก์ชั่น	เส้น

โมดูลนี้ช่วยให้คุณให้บริการเอกสาร API ที่สร้างขึ้นโดยอัตโนมัติที่สร้างขึ้นโดยอัตโนมัติจาก Express ตามไฟล์ swagger.json ผลลัพธ์คือเอกสารประกอบสำหรับ API ของคุณที่โฮสต์จากเซิร์ฟเวอร์ API ของคุณผ่านเส้นทาง

เวอร์ชัน Swagger ถูกดึงจากโมดูล NPM Swagger-ui-dist โปรดใช้ไฟล์ล็อคหรือระบุเวอร์ชันของ Swagger-ui-dist ที่คุณต้องการเพื่อให้แน่ใจว่ามันสอดคล้องกันในสภาพแวดล้อม

คุณอาจสนใจ:

Swagger-JSDOC: ช่วยให้คุณสามารถหาเส้นทางมาร์กอัปด้วยความคิดเห็น JSDOC จากนั้นจะสร้างการกำหนดค่า YML แบบเต็มรูปแบบแบบไดนามิกซึ่งคุณสามารถส่งผ่านไปยังโมดูลนี้เพื่อสร้างเอกสารประกอบ ดูด้านล่างภายใต้ส่วนการใช้งานสำหรับข้อมูลเพิ่มเติม
เครื่องมือ Swagger: เครื่องมือต่าง ๆ รวมถึง Swagger Editor, Swagger Code Gen ฯลฯ

การใช้งาน

ติดตั้งโดยใช้ NPM:

$ npm install swagger-ui-express

Express Setup app.js

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument ) ) ;

หรือถ้าคุณใช้เราเตอร์ด่วน

 const router = require ( 'express' ) . Router ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

router . use ( '/api-docs' , swaggerUi . serve ) ;
router . get ( '/api-docs' , swaggerUi . setup ( swaggerDocument ) ) ;

เปิด http: // <app_host> : <app_port> /api-docs ในเบราว์เซอร์ของคุณเพื่อดูเอกสาร

หากคุณต้องการตั้งค่าการกำหนดเส้นทางตามการชำระเงินของเอกสาร Swagger Swagger-Express-Router

Swagger-jsdoc

หากคุณใช้ swagger-jsdoc เพียงแค่ส่ง swaggerspec ไปยังฟังก์ชั่นการตั้งค่า:

 // Initialize swagger-jsdoc -> returns validated swagger spec in json format
const swaggerSpec = swaggerJSDoc ( options ) ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerSpec ) ) ;

Swagger Explorer

โดยค่าเริ่มต้นแถบ Swagger Explorer จะถูกซ่อนไว้เพื่อแสดงผ่านจริงเป็นคุณสมบัติ 'explorer' ของตัวเลือกไปยังฟังก์ชั่นการตั้งค่า:

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  explorer : true
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

ตัวเลือก Swagger ที่กำหนดเอง

หากต้องการผ่านตัวเลือกที่กำหนดเองเช่นการตรวจสอบความถูกต้องไปยังไคลเอนต์ Swaggerui ส่งผ่านวัตถุเป็นคุณสมบัติ 'swaggeroptions' ของตัวเลือกไปยังฟังก์ชั่นการตั้งค่า:

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  swaggerOptions : {
    validatorUrl : null
  }
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

สำหรับตัวเลือกที่มีอยู่ทั้งหมดโปรดดูการกำหนดค่า UI Swagger

สไตล์ CSS ที่กำหนดเอง

ในการปรับแต่งรูปแบบของหน้า Swagger คุณสามารถผ่าน CSS ที่กำหนดเองเป็นคุณสมบัติ 'CustomCSS' ของตัวเลือกไปยังฟังก์ชั่นการตั้งค่า

เช่นเพื่อซ่อนส่วนหัว Swagger:

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customCss : '.swagger-ui .topbar { display: none }'
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

สไตล์ CSS ที่กำหนดเองจาก URL

นอกจากนี้คุณยังสามารถส่ง URL ไปยังไฟล์ CSS ที่กำหนดเองค่าจะต้องเป็น URL สาธารณะของไฟล์และสามารถสัมพันธ์หรือแน่นอนกับเส้นทาง Swagger

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customCssUrl : '/custom.css'
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

นอกจากนี้คุณยังสามารถผ่านอาร์เรย์ของ URL CSS เพื่อโหลดไฟล์ CSS หลายไฟล์

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customCssUrl : [
    '/custom.css' ,
    'https://example.com/other-custom.css'
  ]
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

JS ที่กำหนดเอง

หากคุณต้องการควบคุม HTML ของคุณอย่างเต็มที่คุณสามารถจัดเตรียมไฟล์ JavaScript ของคุณเองค่ายอมรับเส้นทางสัมบูรณ์หรือเส้นทางที่สัมพันธ์กัน ค่าจะต้องเป็น URL สาธารณะของไฟล์ JS

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customJs : '/custom.js'
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

นอกจากนี้คุณยังสามารถผ่านอาร์เรย์ของ JS URL เพื่อโหลดไฟล์ JS หลายไฟล์

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customJs : [
    '/custom.js' ,
    'https://example.com/other-custom.js'
  ]
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

นอกจากนี้ยังเป็นไปได้ที่จะเพิ่ม JavaScript แบบอินไลน์ไม่ว่าจะเป็นสตริงหรืออาร์เรย์ของสตริง

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customJsStr : 'console.log("Hello World")'
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customJsStr : [
    'console.log("Hello World")' ,
    `
    var x = 1
    console.log(x)
    `
  ]
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

โหลด Swagger จาก URL

ในการโหลด swagger ของคุณจาก URL แทนการฉีดเอกสารให้ส่ง null เป็นพารามิเตอร์แรกและส่งผ่าน URL ที่สัมพันธ์หรือสัมบูรณ์เป็นคุณสมบัติ 'URL' ไปยัง 'Swaggeroptions' ในฟังก์ชั่นการตั้งค่า

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;

var options = {
  swaggerOptions : {
    url : 'http://petstore.swagger.io/v2/swagger.json'
  }
}

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( null , options ) ) ;

ในการโหลดเอกสาร Swagger หลายรายการจาก URL เป็นแบบเลื่อนลงในแถบ Explorer ให้ส่งอาร์เรย์ของวัตถุที่มี name และ url ไปยังคุณสมบัติ 'URL' ไปยัง 'Swaggeroptions' ในฟังก์ชั่นการตั้งค่า

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;

var options = {
  explorer : true ,
  swaggerOptions : {
    urls : [
      {
        url : 'http://petstore.swagger.io/v2/swagger.json' ,
        name : 'Spec1'
      } ,
      {
        url : 'http://petstore.swagger.io/v2/swagger.json' ,
        name : 'Spec2'
      }
    ]
  }
}

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( null , options ) ) ;

ตรวจสอบให้แน่ใจว่าตัวเลือก 'Explorer' ถูกตั้งค่าเป็น 'True' ในตัวเลือกการตั้งค่าของคุณสำหรับการดรอปดาวน์ที่จะมองเห็นได้

โหลด Swagger จากไฟล์ yaml

ในการโหลดข้อมูลจำเพาะของคุณ YAML คุณต้องใช้โมดูลที่สามารถแปลง YAML เป็น JSON; เช่น yaml

 npm install yaml

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const fs = require ( "fs" )
const YAML = require ( 'yaml' )

const file  = fs . readFileSync ( './swagger.yaml' , 'utf8' )
const swaggerDocument = YAML . parse ( file )

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument ) ) ;

แก้ไขไฟล์ Swagger ได้ทันทีก่อนโหลด

ในการตั้งค่าโฮสต์แบบไดนามิกหรือเนื้อหาอื่น ๆ ในไฟล์ Swagger ตามวัตถุคำขอเข้ามาคุณอาจผ่าน JSON ผ่านวัตถุ REQ; เพื่อให้บรรลุสิ่งนี้เพียงแค่ไม่ผ่าน The Swagger Json ไปยังฟังก์ชั่นการตั้งค่าและมันจะมองหา swaggerDoc ในวัตถุ req

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = { }

app . use ( '/api-docs' , function ( req , res , next ) {
    swaggerDocument . host = req . get ( 'host' ) ;
    req . swaggerDoc = swaggerDocument ;
    next ( ) ;
} , swaggerUi . serveFiles ( swaggerDocument , options ) , swaggerUi . setup ( ) ) ;

เอกสารสองเล่ม

ในการเรียกใช้ 2 อินสแตนซ์ UI Swagger ที่มีเอกสาร Swagger ที่แตกต่างกันให้ใช้ฟังก์ชัน ServeFiles แทนฟังก์ชั่นเสิร์ฟ ฟังก์ชั่น ServeFiles มีลายเซ็นเหมือนกับฟังก์ชั่นการตั้งค่า

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocumentOne = require ( './swagger-one.json' ) ;
const swaggerDocumentTwo = require ( './swagger-two.json' ) ;

var options = { }

app . use ( '/api-docs-one' , swaggerUi . serveFiles ( swaggerDocumentOne , options ) , swaggerUi . setup ( swaggerDocumentOne ) ) ;

app . use ( '/api-docs-two' , swaggerUi . serveFiles ( swaggerDocumentTwo , options ) , swaggerUi . setup ( swaggerDocumentTwo ) ) ;

app . use ( '/api-docs-dynamic' , function ( req , res , next ) {
  req . swaggerDoc = swaggerDocument ;
  next ( ) ;
} , swaggerUi . serveFiles ( ) , swaggerUi . setup ( ) ) ;

ลิงก์ไปยังเอกสาร Swagger

ในการแสดงลิงก์ไปยังเอกสาร Swagger สำหรับการดาวน์โหลดภายใน Swagger UI - จากนั้นให้บริการเอกสาร Swagger เป็นจุดสิ้นสุดและใช้ตัวเลือก URL เพื่อชี้ไปที่:

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
    swaggerOptions : {
        url : "/api-docs/swagger.json" ,
    } ,
}
app . get ( "/api-docs/swagger.json" , ( req , res ) => res . json ( swaggerDocument ) ) ;
app . use ( '/api-docs' , swaggerUi . serveFiles ( null , options ) , swaggerUi . setup ( null , options ) ) ;