swagger ui express

Swagger UI Express

ステートメント	枝	関数	線

このモジュールを使用すると、 swagger.jsonファイルに基づいて、Expressから自動生成されたSwagger-UI生成されたAPIドキュメントを提供できます。その結果、ルートを介してAPIサーバーからホストされているAPIのリビングドキュメントが得られます。

Swaggerバージョンは、NPMモジュールSwagger-Ui-Distから引き出されます。ロックファイルを使用するか、環境全体で一貫していることを確認するswagger-ui-distのバージョンを指定してください。

あなたも興味があるかもしれません：

• Swagger-JSDOC：JSDOCコメントでルートをマークアップできます。次に、完全なSwagger YML構成を動的に生成し、このモジュールに渡してドキュメントを作成できます。詳細については、以下の使用セクションをご覧ください。
• Swagger Tools：Swagger Editor、Swagger Code Genなど、さまざまなツール。

使用法

NPMを使用してインストールします：

$ npm install swagger-ui-express

セットアップ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ルーターを使用している場合

 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バーが隠されており、セットアップ関数のオプションの「エクスプローラー」プロパティとしてtrueを表示するために表示されます。

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

カスタムスワッガーオプション

カスタムオプションを渡すことなど、balidatorurll、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ページのスタイルをカスタマイズするには、オプションの「customcss」プロパティとしてセットアップ関数にカスタムCSSを渡すことができます。

たとえば、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 ) ) ;

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からswaggerをロードします

ドキュメントを注入する代わりにURLからswaggerをロードするには、最初のパラメーターとしてnullを渡し、相対URLまたは絶対URLをセットアップ関数の「swaggeroptions」に「url」プロパティとして渡します。

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

Explorer BarのドロップダウンとしてURLから複数のSwaggerドキュメントをロードするには、セットアップ関数の「SwaggerOptions」に「URL」プロパティにnameとurlを備えたオブジェクトの配列を渡します。

 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をロードします

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ファイルを変更します

着信要求オブジェクトに基づいてSwaggerファイルにホストまたはその他のコンテンツを動的に設定するには、REQオブジェクトを介してJSONを渡すことができます。これを達成するには、Swagger JSONをセットアップ関数に渡さないでください。REQ 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 ( ) ) ;

2つのSwaggerドキュメント

さまざまな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 UI内でダウンロードするためのSwaggerドキュメントへのリンクをレンダリングするには、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 ) ) ; 

要件

• ノードV0.10.32以上
• 4以降を高速化します

テスト

• Phantomをインストールします
• npm install
• npm test