swagger ui express下載 - swagger ui express源代碼下載

Swagger UI Express

語句	分支	功能	線

該模塊允許您根據swagger.json文件提供自動生成的Swagger-UI生成的API文檔。結果是通過路由從API服務器託管的API的Live文檔。

Swagger版本是從NPM模塊Swagger-UI-Dist取出的。請使用鎖定文件或指定要確保在環境中保持一致的Swagger-UI端端版本。

您可能也對：

Swagger-JSDOC：允許您用JSDOC評論標記路由。然後，它會動態產生完整的Swagger 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 ) ) ;

或者如果您正在使用Express Router

 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 Document Checkout 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選項

要將自定義選項（例如validatorUrl）傳遞給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 ) ) ;

有關所有可用選項，請參閱Swagger UI配置

自定義CSS樣式

要自定義Swagger頁面的樣式，您可以將自定義CSS作為選項的“ CustomCSS”屬性傳遞給設置功能。

例如，隱藏招搖頭：

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

URL的自定義CSS樣式

您還可以將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 ) ) ;

您還可以將CSS URL數組傳遞到加載多個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文件，Value接受絕對路徑或相對路徑。值必須是JS文件的公共URL。

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

從URL加載招搖

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

要將來自URL的多個Swagger文檔作為資源管理器欄中的下拉文檔，請將帶有name和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”，以便可見的下拉選項。

加載yaml文件的招搖

要加載Swagger規格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 File

要根據傳入的請求對像在Swagger文件中動態設置主機或任何其他內容，您可以通過REQ對像傳遞JSON；為了實現這一目標，不要將Swagger JSON傳遞到設置功能，它將在req對像中尋找swaggerDoc 。

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

兩個搖搖欲墜的文件

要運行具有不同的Swagger文檔的2個Swagger UI實例，請使用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 Doc作為端點，並使用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 ) ) ;