swagger ui express
5.0.1
| Aussagen | Zweige | Funktionen | Linien |
|---|---|---|---|
Mit diesem Modul können Sie automatische Swagger-UI-generierte API-Dokumente aus Express basierend auf einer swagger.json Datei servieren. Das Ergebnis ist eine lebende Dokumentation für Ihre API, die über eine Route von Ihrem API -Server gehostet wird.
Die Swagger-Version wird vom NPM-Modul Swagger-UI-Distel gezogen. Bitte verwenden Sie eine Sperrdatei oder geben Sie die Version von Swagger-UI-DIST an, die sicherstellen möchten, dass sie in verschiedenen Umgebungen konsistent ist.
Möglicherweise interessieren Sie sich auch für:
Installieren Sie mit 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 ) ) ;oder wenn Sie Express -Router verwenden
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 ) ) ; Öffnen Sie http: // <app_host> : <app_port> /API-DOCs in Ihrem Browser, um die Dokumentation anzuzeigen.
Wenn Sie das Routing basierend auf dem Swagger-Dokument-Checkout Swagger-Express-Router einrichten möchten
Wenn Sie Swagger-JSDOC verwenden, geben Sie einfach die SwaggerSpec in die Setup-Funktion ein:
// Initialize swagger-jsdoc -> returns validated swagger spec in json format
const swaggerSpec = swaggerJSDoc ( options ) ;
app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerSpec ) ) ;Standardmäßig ist die Swagger -Explorer -Leiste versteckt, um sie als "Explorer" -Schance der Optionen an die Setup -Funktion anzuzeigen:
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 ) ) ;Um benutzerdefinierte Optionen zu übergeben, z.
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 ) ) ;Für alle verfügbaren Optionen finden Sie in der Swagger UI -Konfiguration
Um den Stil der Swagger -Seite anzupassen, können Sie benutzerdefinierte CSS als 'CustomCSS' -Eigenschaft der Optionen an die Setup -Funktion übergeben.
ZB den Prahlerkopf zu verbergen:
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 ) ) ;Sie können die URL auch an eine benutzerdefinierte CSS -Datei übergeben, der Wert muss die öffentliche URL der Datei sein und kann relativ oder absolut für den Swagger -Pfad sein.
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 ) ) ;Sie können auch eine Reihe von CSS -URLs übergeben, um mehrere CSS -Dateien zu laden.
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 ) ) ;Wenn Sie die volle Kontrolle über Ihre HTML -Datei haben möchten, können Sie Ihre eigene JavaScript -Datei angeben, der Wert akzeptiert den absoluten oder relativen Pfad. Der Wert muss die öffentliche URL der JS -Datei sein.
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 ) ) ;Sie können auch ein Array von JS -URLs übergeben, um mehrere JS -Dateien zu laden.
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 ) ) ;Es ist auch möglich, Inline -JavaScript entweder als Zeichenfolge oder als Zeichenfolge hinzuzufügen.
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 ) ) ; Um Ihre Prahlerei aus einer URL zu laden, anstatt das Dokument zu injizieren, übergeben Sie null als erster Parameter und übergeben Sie die relative oder absolute URL als 'URL' -Eigenschaft an 'Swaggeroptions' in der Setup -Funktion.
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 ) ) ; Um mehrere Prahler -Dokumente aus URLs als Dropdown in der Explorer -Leiste zu laden, übergeben Sie in der Setup -Funktion ein Objekt -Objekt mit name und url an die Eigenschaft "URLs" an "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 ) ) ;Stellen Sie sicher, dass die Option "Explorer" in Ihren Setup -Optionen auf "True" eingestellt ist, damit die Dropdown -Art zu sichtbar ist.
So laden Sie Ihre Swagger -Spezifikation YAML -Datei Sie müssen ein Modul verwenden, um YAML in JSON umzuwandeln. Zum Beispiel 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 ) ) ; Um den Host oder einen anderen Inhalt dynamisch in der Swagger -Datei basierend auf dem eingehenden Anforderungsobjekt festzulegen, können Sie den JSON über das REQ -Objekt übergeben. Um dies zu erreichen, übergeben Sie den Swagger JSON nicht an die Setup -Funktion und sucht im req -Objekt nach 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 ( ) ) ;Um 2 Swagger UI -Instanzen mit verschiedenen Prahler -Dokumenten auszuführen, verwenden Sie die Services -Funktion anstelle der Servic -Funktion. Die Funktion Services hat die gleiche Signatur wie die Einstellungsfunktion.
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 ( ) ) ;Um einen Link zum Swagger -Dokument für das Herunterladen in der SWAGGE -Benutzeroberfläche zu rendern, servieren Sie den Swagger -Dokument als Endpunkt und verwenden Sie die URL -Option, um darauf zu verweisen:
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 ) ) ; npm installnpm test
