web-dev-qa-db-fra.com

Générer un document Swagger pour le serveur NodeJS existant

Selon site Web Swagger , il existe deux approches: ascendante et descendante.

J'ai un serveur NodeJS existant que j'aimerais déployer dans l'environnement Azure, qui nécessite un document swagger (API APP).

Est-ce que quelqu'un connaît un outil pour générer le swagger en utilisant le code? Encore mieux si vous pouviez pointer un tutoriel. Je ne l'ai pas trouvé.

node.jsapiazureserverswagger
18
Ernani

Il n’est pas difficile d’intégrer Swagger dans les applications express existantes après ce tutoriel .

Généralement, nous pouvons suivre ces étapes:

  1. Ajoutez les dépendances dans notre package.json Et exécutez npm install Pour les installer. Les dépendances doivent être:

    "dependencies": {
        "swagger-node-express": "~2.0",
        "minimist": "*",
        "body-parser": "1.9.x",
        ...
}

  2. Téléchargez le projet Zip de Swagger-UI , copiez le dossier dist dans le répertoire racine de notre projet, le répertoire devrait presque comme:

enter image description here

  1. Présentez les dépendances au début de app.js:

    var argv = require('minimist')(process.argv.slice(2));
var swagger = require("swagger-node-express");
var bodyParser = require( 'body-parser' );

  2. Configurez un sous-chemin pour le swagger doc:

    var subpath = express();
app.use(bodyParser());
app.use("/v1", subpath);
swagger.setAppHandler(subpath);

  3. Assurez-vous que /dist Est capable de servir des fichiers statiques dans express: app.use(express.static('dist'));

  4. Définissez les informations pour l'API:

    swagger.setApiInfo({
    title: "example API",
    description: "API to do something, manage something...",
    termsOfServiceUrl: "",
    contact: "[email protected]",
    license: "",
    licenseUrl: ""
});

  5. Introduisez /dist/index.html Pour l'interface utilisateur swagger:

    subpath.get('/', function (req, res) {
    res.sendfile(__dirname + '/dist/index.html');
});

  6. Complétez les configurations swagger:

    swagger.configureSwaggerPaths('', 'api-docs', '');

var domain = 'localhost';
if(argv.domain !== undefined)
    domain = argv.domain;
else
    console.log('No --domain=xxx specified, taking default hostname "localhost".');
var applicationUrl = 'http://' + domain;
swagger.configure(applicationUrl, '1.0.0');

  7. Configurez la dépendance du fichier doc dans /dist/index.html:

    if (url && url.length > 1) {
    url = decodeURIComponent(url[1]);
} else {
    <del>url = "http://petstore.swagger.io/v2/swagger.json";</del>
    url = "/api-docs.json";
}

  8. Créez le fichier api-docs.json Avec les informations de vos API, placez-le dans le dossier dist.

Exécutez l'application Express sur local, visitez http://localhost:3000/v1, Nous pouvons vérifier le doc swagger.

Voici mon test repo échantillon pour votre référence.

19
Gary Liu - MSFT

La question est un peu vieille mais quand même. Il est possible de générer une spécification Swagger (OpenAPI) complètement automatique simplement en incorporant un middleware d'analyse comme celui-ci: https://github.com/mpashkovskiy/express-oas-generator

const express = require('express');    
const expressOasGenerator = require('express-oas-generator');
let app = express();
expressOasGenerator.init(app, {});

exécutez un client ou REST les tests API contre votre service et ouvrez http: // Host: port/api-docs

5
mpashkovskiy

À ma connaissance, vos options sont:

  1. Utiliser swagger-node-express ce qui est très lourd à mon avis.
  2. Écrire le document swagger manuellement vous-même à l'aide de éditeur de swagger comme suggéré dans ce Réponse SO

Si vous optez pour l'option 2, vous pouvez utiliser swagger-ui-express pour générer le swagger-ui

0
Ahmad Abdelghany