Composants principaux de Swagger

Swagger est un ensemble d'outils open source construit autour de la spécification OpenAPI, utilisé pour concevoir, construire, documenter et utiliser des API RESTful.

Swagger fournit un moyen standardisé de décrire la structure des API, permettant aux développeurs et aux machines de comprendre la fonctionnalité d'une API sans accéder au code source ni à d'autres documentations.

Les valeurs fondamentales de Swagger sont :

  • Normalisation: Fournit un format unifié de description d'API
  • Visualisation: Génère automatiquement une documentation API interactive
  • Testabilité: Permet de tester les points de terminaison d'API directement dans la documentation
  • Génération de code: Prend en charge la génération de code côté client et côté serveur dans plusieurs langages

Composants principaux de Swagger

ComposantEntréeSortieÉtape applicable
Swagger EditorÉcrire manuellement YAML/JSONDocumentation API avec aperçu en temps réelPhase de conception d'API
Swagger UIFichier OpenAPIDocumentation web interactivePhase de développement/test
Swagger CodegenFichier OpenAPICode client/serveurÉtape de collaboration frontend-backend

Organigramme de collaboration des composants :

Swagger Editor（设计API）  
  ↓  
OpenAPI 规范文件（YAML/JSON）  
  ↓  
Swagger UI（展示文档） ou  Swagger Codegen（生成代码）

Explication des composants principaux de Swagger

1. Swagger Editor

Swagger Editor est un éditeur visuel basé sur navigateur pour écrire et prévisualiser des spécifications OpenAPI (format YAML/JSON) en temps réel.

Swagger Editor fournit la coloration syntaxique, l'auto-complétion et la validation des erreurs.

Les fonctionnalités de génération de code, de sauvegarde et d'exportation de Swagger Editor ont maintenant été intégrées dans SmartBear API Hub. Adresse d'accès :https://try.platform.smartbear.com/new-organization。

Cas d'utilisation :

  • Concevoir rapidement des prototypes d'API
  • Apprendre la syntaxe des spécifications OpenAPI

Accéder à l'éditeur en ligne Swagger Editor :https://editor.swagger.io/

Entrez le code YAML suivant (définit un point de terminaison GET /users simple) :

Exemple

span style="color: green;">
openapi: 3.0.3
informations:
  title: EXEMPLE Système de gestion des utilisateurs
  version: 1.0.0
chemins:
  /users:
    get:
      summary: Obtenir la liste des utilisateurs
      responses:
        '200':
          description: Retourne avec succès la liste des utilisateurs
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

Le côté droit affichera la documentation de l'API et l'interface utilisateur interactive en temps réel.

Swagger UI

Swagger UI convertit les spécifications OpenAPI en documentation interactive visuelle et prend en charge le test des API directement dans le navigateur.

Swagger UI génère automatiquement des exemples de requête, des modèles de réponse et une interface de débogage.

Swagger UI : https://swagger.io/tools/swagger-ui/

Cas d'utilisation :

  • Partager la documentation d'API au sein d'une équipe
  • Les développeurs frontend déboguent les API

Exemple d'intégration (avec Node.js), installez les dépendances :

npm install swagger-ui-express swagger-jsdoc

Créer un fichier de configuration swagger.js :

Exemple

const swaggerJSDoc = require('swagger-jsdoc');
const options = {
  définition: {
    openapi: '3.0.0',
    info: { title: 'API utilisateur', version: '1.0.0' },
  },
  apis: ['./routes/*.js'], // Analyser les commentaires dans les fichiers de routes
};
const swaggerSpec = swaggerJSDoc(options);
module.exports = swaggerSpec;

Monter l'interface utilisateur dans Express :

Exemple

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerSpec = require('./swagger');

const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

Visitez http://localhost:3000/api-docs pour consulter la documentation.

Swagger Codegen

Swagger Codegen génère automatiquement des SDK clients (par ex. Java, Python) ou du code stub serveur (par ex. Spring, Flask) à partir des spécifications OpenAPI.

Swagger Codegen prend en charge les modèles personnalisés.

Page de téléchargement :https://swagger.io/tools/swagger-codegen/

Cas d'utilisation :

  • Générer rapidement le code client pour les appels d'API
  • Développement automatisé des interfaces côté serveur

Exemple d'opération (générer un client Java en ligne de commande), télécharger Swagger Codegen CLI :

wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.35/swagger-codegen-cli-3.0.35.jar -O swagger-codegen-cli.jar

Générer le code :

java -jar swagger-codegen-cli.jar generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -l java \
  -o ./petstore-api-client

Swagger Hub (extension facultative)

Swagger Hub est la plateforme cloud de Swagger, offrant une conception collaborative, une gestion des versions et une documentation hébergée.

Swagger Hub prend en charge la collaboration en équipe et la gestion du cycle de vie des API.

Cas d'utilisation :

  • Gestion de projets API de niveau entreprise
  • Équipes distribuées ayant besoin d'une collaboration en ligne

Adresse d'accès :https://swagger.io/api-hub/

Autres extensions