swagger ui express

Swagger UI Express

Pernyataan	Cabang	Fungsi	Baris

Modul ini memungkinkan Anda untuk melayani dokumen API yang dihasilkan dari API yang dihasilkan secara otomatis dari Express, berdasarkan pada file swagger.json . Hasilnya adalah dokumentasi hidup untuk API Anda yang dihosting dari server API Anda melalui rute.

Versi Swagger ditarik dari modul NPM Swagger-ui-Dist. Harap gunakan file kunci atau tentukan versi Swagger-ui-Dist yang ingin Anda pastikan konsisten di seluruh lingkungan.

Anda mungkin juga tertarik:

• Swagger-jsdoc: Memungkinkan Anda untuk menandai rute dengan komentar JSDOC. Kemudian menghasilkan konfigurasi YML penuh kesombongan secara dinamis, yang dapat Anda lewati ke modul ini untuk menghasilkan dokumentasi. Lihat di bawah di bawah bagian Penggunaan untuk info lebih lanjut.
• Alat Swagger: Berbagai alat, termasuk editor Swagger, gen Swagger Code dll.

Penggunaan

Instal menggunakan 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 ) ) ;

atau jika Anda menggunakan router ekspres

 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 ) ) ;

Buka http: // <app_host> : <app_port> /API-DOCS di browser Anda untuk melihat dokumentasi.

Jika Anda ingin mengatur perutean berdasarkan Dokumen Swagger Checkout Swagger-Express-Router

Swagger-jsdoc

Jika Anda menggunakan Swagger-jsdoc cukup lewati Swaggerspec ke fungsi pengaturan:

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

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

Penjelajah Swagger

Secara default, Bilah Penjelajah Swagger disembunyikan, untuk menampilkannya adalah benar sebagai properti 'penjelajah' dari opsi ke fungsi pengaturan:

 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 ) ) ;

Opsi Swagger Kustom

Untuk lulus opsi khusus misalnya validatorurl, ke klien Swaggerui lulus objek sebagai properti 'SwaggerOptions' dari opsi ke fungsi pengaturan:

 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 ) ) ;

Untuk semua opsi yang tersedia, lihat Konfigurasi UI Swagger

Gaya CSS khusus

Untuk menyesuaikan gaya halaman Swagger, Anda dapat melewati CSS khusus sebagai properti 'CustomCSS' dari opsi ke fungsi pengaturan.

Misalnya untuk menyembunyikan sundulan 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 ) ) ;

Gaya CSS khusus dari URL

Anda juga dapat meneruskan URL ke file CSS khusus, nilainya harus menjadi URL publik dari file dan dapat relatif atau mutlak ke jalur angkuh.

 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 ) ) ;

Anda juga dapat melewati array URL CSS untuk memuat beberapa file 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 Kustom

Jika Anda ingin memiliki kontrol penuh atas HTML Anda, Anda dapat memberikan file JavaScript Anda sendiri, Nilai menerima jalur absolut atau relatif. Nilai harus menjadi URL publik dari file 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 ) ) ;

Anda juga dapat melewati serangkaian URL JS untuk memuat beberapa file 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 ) ) ;

Dimungkinkan juga untuk menambahkan inline JavaScript, baik sebagai string atau array string.

 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 ) ) ;

Memuat kesombongan dari url

Untuk memuat kesombongan Anda dari URL alih -alih menyuntikkan dokumen, lulus null sebagai parameter pertama, dan lulus URL relatif atau absolut sebagai properti 'URL' ke 'SwaggerOptions' dalam fungsi pengaturan.

 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 ) ) ;

Untuk memuat beberapa dokumen Swagger dari URL sebagai dropdown di bilah Explorer, berikan array objek dengan name dan url ke properti 'URL' ke 'SwaggerOptions' dalam fungsi pengaturan.

 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 ) ) ;

Pastikan opsi 'Explorer' diatur ke 'true' di opsi pengaturan Anda agar dropdown terlihat.

Muat Swagger dari file YAML

Untuk memuat file spesifikasi YAML Spesifikasi Anda, Anda perlu menggunakan modul yang dapat mengonversi YAML ke JSON; misalnya 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 ) ) ;

Memodifikasi file Swagger dengan cepat sebelum memuat

Untuk secara dinamis mengatur host, atau konten lainnya, dalam file Swagger berdasarkan objek permintaan yang masuk Anda dapat melewati JSON melalui objek Req; Untuk mencapai hal ini, jangan lewati Swagger JSON ke fungsi pengaturan dan itu akan mencari swaggerDoc di objek 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 ( ) ) ;

Dua dokumen kesombongan

Untuk menjalankan 2 instance UI Swagger dengan dokumen kesombongan yang berbeda, gunakan fungsi serveFiles alih -alih fungsi servis. Fungsi ServeFiles memiliki tanda tangan yang sama dengan fungsi pengaturan.

 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 ( ) ) ;

Tautan ke Dokumen Swagger

Untuk membuat tautan ke dokumen Swagger untuk diunduh dalam UI Swagger - lalu sajikan dokumen Swagger sebagai titik akhir dan gunakan opsi URL untuk menunjuknya:

 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 ) ) ; 

Persyaratan

• Node v0.10.32 atau lebih
• Ekspresikan 4 atau lebih

Pengujian

• Pasang Phantom
• npm install
• npm test