swagger ui express
5.0.1
| Affirmations | Branches | Fonctions | Lignes |
|---|---|---|---|
Ce module vous permet de servir les documents API générés par Swagger-UI générés par Auto à partir d'express, basé sur un fichier swagger.json . Le résultat est la documentation vivante pour votre API hébergée à partir de votre serveur API via un itinéraire.
La version Swagger est tirée du module NPM Swagger-Ui-Dist. Veuillez utiliser un fichier de verrouillage ou spécifier la version de Swagger-Ui-Dist que vous souhaitez vous assurer qu'elle est cohérente entre les environnements.
Vous pouvez également vous intéresser:
Installer à l'aide de 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 ) ) ;ou si vous utilisez le routeur 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 ) ) ; Ouvrez http: // <app_host> : <app_port> / api-docs dans votre navigateur pour afficher la documentation.
Si vous souhaitez configurer le routage basé sur le document Swagger Checkout Swagger-Express-Router
Si vous utilisez Swagger-Jsdoc, passez simplement le swaggerspec dans la fonction de configuration:
// Initialize swagger-jsdoc -> returns validated swagger spec in json format
const swaggerSpec = swaggerJSDoc ( options ) ;
app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerSpec ) ) ;Par défaut, la barre d'explorateur Swagger est masquée, pour l'afficher passe vrai en tant que propriété «Explorer» des options à la fonction de configuration:
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 ) ) ;Pour passer les options personnalisées, par exemple, validatorurl, au client Swaggerui transmettent un objet en tant que propriété «SwaggerOptions» des options à la fonction de configuration:
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 ) ) ;Pour toutes les options disponibles, reportez-vous à la configuration de l'interface utilisateur Swagger
Pour personnaliser le style de la page Swagger, vous pouvez passer CSS personnalisé en tant que propriété «CustomCSS» des options à la fonction de configuration.
Par exemple pour cacher l'en-tête de fanfaronnade:
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 ) ) ;Vous pouvez également transmettre l'URL à un fichier CSS personnalisé, la valeur doit être l'URL publique du fichier et peut être relative ou absolue au chemin de fanfaron.
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 ) ) ;Vous pouvez également passer un tableau d'URL CSS pour charger plusieurs fichiers 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 ) ) ;Si vous souhaitez avoir un contrôle total sur votre HTML, vous pouvez fournir votre propre fichier JavaScript, la valeur accepte le chemin absolu ou relatif. La valeur doit être l'URL publique du fichier 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 ) ) ;Vous pouvez également passer un tableau d'URL JS pour charger plusieurs fichiers 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 ) ) ;Il est également possible d'ajouter en ligne JavaScript, soit en tant que chaîne, soit en tableau de chaîne.
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 ) ) ; Pour charger votre fanfaron à partir d'une URL au lieu d'injecter le document, passez null comme premier paramètre et transmettez l'URL relative ou absolue en tant que propriété «URL» à «Swaggeroptions» dans la fonction de configuration.
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 ) ) ; Pour charger plusieurs documents Swagger des URL comme une liste déroulante dans la barre d'explorateur, passez un tableau d'objet avec name et url vers la propriété «URL» à «Swaggeroptions» dans la fonction de configuration.
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 ) ) ;Assurez-vous que l'option «Explorer» est définie sur «vrai» dans vos options de configuration pour que la liste déroulante soit visible.
Pour charger le fichier YAML de votre spécification Swagger, vous devez utiliser un module capable de convertir YAML en JSON; Par exemple 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 ) ) ; Pour définir dynamiquement l'hôte, ou tout autre contenu, dans le fichier Swagger en fonction de l'objet de demande entrant, vous pouvez transmettre le JSON via l'objet req; Pour y parvenir, ne passez pas le JSON The Swagger à la fonction de configuration et il recherchera swaggerDoc dans l'objet 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 ( ) ) ;Pour exécuter 2 instances d'interface utilisateur Swagger avec différents documents de fanfaronnade, utilisez la fonction ServeFiles au lieu de la fonction de service. La fonction ServeFiles a la même signature que la fonction de configuration.
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 ( ) ) ;Pour rendre un lien vers le document Swagger pour le téléchargement dans l'interface utilisateur de Swagger - puis servez le Doc Swagger comme point de terminaison et utilisez l'option URL pour le pointer:
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
