Swagger UI et tutoriel de publication de documentation

Swagger UI est un outil de visualisation de documentation API basé sur la spécification OpenAPI (anciennement la spécification Swagger). Il peut convertir les documents de spécification API en une interface de documentation API interactive.

Grâce à Swagger UI, les développeurs et les utilisateurs peuvent :

  • Afficher des informations détaillées sur l'API
  • Tester les requêtes API directement dans l'interface
  • Consulter des exemples de requête et de réponse
  • Comprendre les fonctionnalités et les paramètres des différents points de terminaison d'API

Avantages de Swagger UI

  1. Visualisation: Fournit une interface de documentation API claire et intuitive
  2. Interactivité: Prend en charge les tests d'API en ligne sans outils supplémentaires
  3. Mises à jour en temps réel: La documentation est automatiquement mise à jour après les modifications du code
  4. Normalisation: Basée sur la spécification OpenAPI, garantissant la cohérence
  5. Prise en charge inter-langages: Applicable à divers langages de programmation et frameworks

Intégration de Swagger UI

1. Intégration dans un projet Spring Boot

Ajouter les dépendances

Danspom.xmlAjoutez les dépendances suivantes :

Exemple

<!-- Springfox Swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

<!-- Springfox Swagger UI -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

Ou utilisez SpringDoc OpenAPI :

Exemple

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version>
</dependency>

Configurer Swagger

Exemple

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Documentation de l'API")
                .description("Description détaillée de l'API")
                .version("1.0.0")
                .contact(new Contact("Équipe de développement", "https://example.com", "team@example.com"))
                .build();
    }
}

Pour SpringDoc OpenAPI :

Exemple

import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Documentation de l'API")
                        .version("1.0.0")
                        .description("Description détaillée de l'API")
                        .contact(new Contact()
                                .name("Équipe de développement")
                                .email("team@example.com")
                                .url("https://example.com")));
    }

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public-apis")
                .pathsToMatch("/api/**")
                .build();
    }
}

2. Intégration dans un projet Node.js Express

Installer les dépendances

npm install swagger-jsdoc swagger-ui-express --save

Configurer Swagger

Exemple

const express = require('express');
const swaggerJsDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const app = express();

// Configuration Swagger
const swaggerOptions = {
  définition: {
    openapi: '3.0.0',
    informations: {
      title: "Description de l'API",
      version: '1.0.0',
      description: Description détaillée de l'API,
      contact: {
        name: 'Équipe de développement',
        email: 'team@example.com',
        url: 'https://example.com'
      }
    },
    servers: [
      {
        url: 'http://localhost:3000',
        description: 'Serveur de développement'
      }
    ]
  },
  apis: ['./routes/*.js'] // Chemin vers le fichier de route de l'API
};

const swaggerDocs = swaggerJsDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

// ... autres routes et intergiciels

app.listen(3000, () => {
  console.log('Serveur en cours d'exécution sur http://localhost:3000');
  console.log('La documentation de l'API est accessible à http://localhost:3000/api-docs');
});

3. Utilisation dans un projet Python FastAPI

FastAPI intègre Swagger UI par défaut:

Exemple

from fastapi import FastAPI

app = FastAPI(
    title="Documentation de l'API",
    description="Description détaillée de l'API",
    version="1.0.0",
    contact={
        "name": "Équipe de développement",
        "email": "team@example.com",
        "url": "https://example.com",
    },
)

@app.get("/")
async def root():
    return {"message": "Hello World"}

Swagger UI est accessible par défaut au chemin /docs. Vous pouvez consulter la documentation en visitant http://localhost:8000/docs.

Pour plus de détails, voir :Documentation interactive de l'API FastAPI


Rédaction de la documentation d'API

1. Annotations de documentation d'API dans un projet Spring Boot

Exemple

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
@Api(tags = "Gestion des utilisateurs")
public class UserController {

    @ApiOperation(value = "Obtenir la liste des utilisateurs", notes = "Obtenir toutes les informations des utilisateurs avec pagination")
    @ApiResponses({
        @ApiResponse(code = 200, message = "Succès"),
        @ApiResponse(code = 400, message = "Paramètres de requête non valides"),
        @ApiResponse(code = 500, message = "Erreur interne du serveur")
    })
    @GetMapping("/")
    public Page<User> getUsers(
            @ApiParam(value = "Numéro de page", required = true) @RequestParam int page,
            @ApiParam(value = "Nombre d'enregistrements par page", required = true) @RequestParam int size) {
        // Logique métier
        return userService.getUsers(page, size);
    }

    @ApiOperation(value = "Obtenir un seul utilisateur", notes = "Obtenir les informations de l'utilisateur par ID")
    @GetMapping("/{id}")
    public User getUser(
            @ApiParam(value = "ID de l'utilisateur", required = true) @PathVariable Long id) {
        // Logique métier
        return userService.getUser(id);
    }

    @ApiOperation(value = "Créer un utilisateur", notes = "Créer un nouvel utilisateur")
    @PostMapping("/")
    public User createUser(
            @ApiParam(value = "Informations de l'utilisateur", required = true) @RequestBody UserDTO userDTO) {
        // Logique métier
        return userService.createUser(userDTO);
    }
}

Pour SpringDoc OpenAPI :

Exemple

import io.swagger.v3.oas.annotations.*;
import io.swagger.v3.oas.annotations.media.*;
import io.swagger.v3.oas.annotations.responses.*;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
@Tag(name = "Gestion des utilisateurs", description = "API liées aux utilisateurs")
public class UserController {

    @Opération(
        summary = "Obtenir la liste des utilisateurs",
        description = "Obtenir toutes les informations utilisateur avec pagination"
    )
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Succès"),
        @ApiResponse(responseCode = "400", description = "Paramètres de requête invalides"),
        @ApiResponse(responseCode = "500", description = "Erreur interne du serveur")
    })
    @GetMapping("/")
    public Page<User> getUsers(
            @Parameter(description = "Numéro de page", required = true) @RequestParam int page,
            @Parameter(description = "Nombre d'enregistrements par page", required = true) @RequestParam int size) {
        // Logique métier
        return userService.getUsers(page, size);
    }
}

2. Commentaires de documentation API dans un projet Node.js Express

Exemple

/**
 * @swagger
 * /api/users:
 * get:
* summary: Obtenir la liste des utilisateurs
* description: Récupérer toutes les informations des utilisateurs avec pagination
* tags: [Gestion des utilisateurs]
 * parameters:
 * - in: query
 * name: page
 * schema:
 * type: integer
 * required: true
* description: Numéro de page
 * - in: query
 * name: size
 * schema:
 * type: integer
 * required: true
* description: Nombre d'enregistrements par page
 * responses:
 *       200:
* description: Succès
 * content:
 * application/json:
 * schema:
 * type: object
 * properties:
 * data:
 * type: array
 * items:
 * $ref: '#/components/schemas/User'
 * total:
 * type: integer
 *       400:
* description: Paramètres de requête non valides
 *       500:
* description: Erreur interne du serveur
 */

router.get('/users', (req, res) => {
  // Logique métier
});

/**
 * @swagger
 * components:
 * schemas:
 * User:
 * type: object
 * required:
 * - name
 * - email
 * properties:
 * id:
 * type: integer
* description: ID de l'utilisateur
 * name:
 * type: string
* description: Nom d'utilisateur
 * email:
 * type: string
 * format: email
* description: E-mail de l'utilisateur
 */

3. Documentation de l'API dans un projet Python FastAPI

Exemple

from fastapi import FastAPI, Query, Path
from pydantic import BaseModel
from typing import List, Optional

app = FastAPI(title="API de gestion des utilisateurs")

class User(BaseModel):
    id: int
    name: str
    email: str
   
    class Config:
        schema_extra = {
            "example": {
                "id": 1,
                "name": "Zhang San",
                "email": "zhangsan@example.com"
            }
        }

@app.get(
    "/api/users/",
    summary="Obtenir la liste des utilisateurs",
    description="Obtenir toutes les informations utilisateur avec pagination",
    response_model=List[User],
    tags=["Gestion des utilisateurs"]
)
async def get_users(
    page: int = Query(..., description="Numéro de page", ge=1),
    size: int = Query(..., description="Nombre d'enregistrements par page", ge=1, le=100)
):
    # Logique métier
    return [
        {"id": 1, "name": "Zhang San", "email": "zhangsan@example.com"},
        {"id": 2, "name": "Li Si", "email": "lisi@example.com"}
    ]

@app.get(
    "/api/users/{user_id}",
    summary="Obtenir un utilisateur unique",
    description="Obtenir les informations de l'utilisateur par ID",
    response_model=User,
    tags=["Gestion des utilisateurs"]
)
async def get_user(
    user_id: int = Path(..., description="ID utilisateur", ge=1)
):
    # Logique métier
    return {"id": user_id, "name": "Zhang San", "email": "zhangsan@example.com"}

Personnalisation de Swagger UI

1. Configuration personnalisée de Spring Boot

Exemple

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
            .paths(PathSelectors.regex("/api/.*"))
            .build()
            .apiInfo(apiInfo())
            .useDefaultResponseMessages(false)  // Désactiver les messages de réponse par défaut
            .globalResponseMessage(RequestMethod.GET, globalResponses())  // Messages de réponse globaux personnalisés
            .securitySchemes(Arrays.asList(apiKey()))  // Configurer l'authentification de sécurité
            .securityContexts(Arrays.asList(securityContext()));  // Configurer le contexte de sécurité
}

private List<ResponseMessage> globalResponses() {
    return Arrays.asList(
            new ResponseMessageBuilder().code(200).message("Succès").build(),
            new ResponseMessageBuilder().code(400).message("Paramètres de requête non valides").build(),
            new ResponseMessageBuilder().code(401).message("Non autorisé").build(),
            new ResponseMessageBuilder().code(403).message("Interdit").build(),
            new ResponseMessageBuilder().code(500).message("Erreur interne du serveur").build()
    );
}

private ApiKey apiKey() {
    return new ApiKey("JWT", "Authorization", "header");
}

private SecurityContext securityContext() {
    return SecurityContext.builder()
            .securityReferences(defaultAuth())
            .forPaths(PathSelectors.regex("/api/.*"))
            .build();
}

private List<SecurityReference> defaultAuth() {
    AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
    authorizationScopes[0] = authorizationScope;
    return Arrays.asList(new SecurityReference("JWT", authorizationScopes));
}

2. Configuration personnalisée d'Express

Exemple

const options = {
  customCss: '.swagger-ui .topbar { display: none }',  // CSS personnalisé
  customSiteTitle: "Centre de documentation de l'API",  // Titre de la page
  customfavIcon: "/favicon.png",  // Icône personnalisée
  swaggerOptions: {
    persistAuthorization: true,  // Conserver les informations d'autorisation
    docExpansion: 'none',  // Replier toutes les interfaces par défaut
    tagsSorter: 'alpha',   // Trier les tags par ordre alphabétique
    operationsSorter: 'alpha', // Trier les opérations par ordre alphabétique
    defaultModelsExpandDepth: -1, // Masquer les modèles
    filter: true,  // Activer le filtrage
  }
};

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs, options));

3. Configuration personnalisée de FastAPI

Exemple

from fastapi import FastAPI
from fastapi.openapi.docs import get_swagger_ui_html
from fastapi.staticfiles import StaticFiles

app = FastAPI(
    title="Documentation de l'interface API",
    docs_url=None,  # Désactiver l'interface Swagger UI par défaut
)

app.mount("/static", StaticFiles(directory="static"), name="static")

@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
    return get_swagger_ui_html(
        openapi_url=app.openapi_url,
        title=app.title + " - Documentation de l'API",
        oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
        swagger_js_url="/static/swagger-ui-bundle.js",
        swagger_css_url="/static/swagger-ui.css",
        swagger_favicon_url="/static/favicon.png",
        swagger_ui_parameters={
            "docExpansion": "none",
            "defaultModelsExpandDepth": -1,
            "filter": True,
        }
    )

Publication de la documentation

1. Publication interne

Pour une utilisation interne à l'équipe, vous pouvez accéder directement à l'interface Swagger UI au sein de l'application :

  • Spring Boot : http://your-app-host:port/swagger-ui/index.html
  • Express : http://your-app-host:port/api-docs
  • FastAPI : http://your-app-host:port/docs

2. Génération de documentation statique

Utiliser Swagger Codegen pour générer une documentation statique

# 安装 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

# 生成静态 HTML 文档
java -jar swagger-codegen-cli.jar generate -i http://your-app-host:port/v3/api-docs -l html2 -o ./api-docs

Utiliser Redoc pour générer une documentation statique

# 安装 redoc-cli
npm install -g redoc-cli

# 生成静态 HTML 文档
redoc-cli bundle http://your-app-host:port/v3/api-docs -o ./api-docs/index.html

3. Intégration dans un pipeline CI/CD

Ajoutez des étapes de génération et de publication de documentation au pipeline CI/CD :

Exemple de pipeline Jenkins

Exemple

pipeline {
    agent any
   
    stages {
        // ... autres étapes de build et de test
       
        stage('Générer la documentation API') {
            steps {
                sh 'java -jar swagger-codegen-cli.jar generate -i http://your-app-host:port/v3/api-docs -l html2 -o ./api-docs'
            }
        }
       
        stage('Publier la documentation') {
            steps {
                // Publier sur le serveur de fichiers statiques Nginx
                sh 'rsync -avz --delete ./api-docs/ user@doc-server:/var/www/api-docs/'
               
                // Ou publier vers un stockage objet (par ex., AWS S3)
                sh 'aws s3 sync ./api-docs/ s3://your-bucket/api-docs/ --delete'
            }
        }
    }
}

Exemple de workflow GitHub Actions

Exemple

name: Générer et déployer la documentation API

sur:
  push:
    branches: [ main ]

jobs:
  build-et-deploy:
    runs-on: ubuntu-latest
   
    steps:
    - uses: actions/checkout@v2
   
    - name: Configurer le JDK
      uses: actions/setup-java@v2
      with:
        distribution: 'adopt'
        java-version: '11'
   
    - name: Compiler l'application
      run: ./mvnw clean package
   
    - name: Démarrer l'application
      run: |
        java -jar target/your-app.jar &
        sleep 30# Attendre le démarrage de l'application
   
    - name: Générer la documentation de l'API
      run: |
        wget -q 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
        java -jar swagger-codegen-cli.jar generate -i http://localhost:8080/v3/api-docs -l html2 -o ./api-docs
   
    - name: Déployer sur GitHub Pages
      uses: JamesIves/github-pages-deploy-action@4.1.5
      with:
        branch: gh-pages
        folder: api-docs

4. Utilisation d'une plateforme de gestion de documentation d'API

Outre l'auto-déploiement, vous pouvez également utiliser des plateformes professionnelles de gestion de documentation d'API :

  • Swagger Hub: fournit des services d'hébergement pour la conception et la documentation d'API
  • Postman: vous permet de tester des API et de publier également de la documentation d'API
  • ReadMe.io: fournit une gestion complète de la documentation d'API et un portail pour développeurs
  • Stoplight: fournit des outils de conception, de documentation et de gouvernance d'API

5. Déploiement de Swagger UI avec Docker

Exemple

FROM swaggerapi/swagger-ui:latest

# Définir les variables d'environnement
ENV SWAGGER_JSON=/swagger/openapi.json
ENV BASE_URL=/api-docs

# Copier le fichier de spécification OpenAPI
COPY openapi.json /swagger/

# Exposer le port
EXPOSE 8080

# Démarrer Swagger UI
CMD ["sh", "/usr/share/nginx/docker-run.sh"]

Construire et exécuter :

docker build -t my-swagger-ui .
docker run -p 8080:8080 my-swagger-ui

Accès : http://localhost:8080/api-docs


Bonnes pratiques

1. Normes de documentation

  • Soyez concis et clair: Les descriptions doivent être concises et ciblées
  • Gestion des groupes: Utilisez des tags pour regrouper logiquement les API
  • Fournir des exemples: Fournissez des exemples pour les requêtes et les réponses
  • Normaliser la gestion des erreurs: Normalisez le format des réponses d'erreur et les codes de statut
  • Contrôle de version: Indiquez clairement les informations de version de l'API dans la documentation

2. Configuration de la sécurité

  • Traitement des informations sensibles: N'exposez pas d'informations sensibles dans la documentation
  • Configuration de l'environnement de production: Désactivez ou restreignez éventuellement l'accès à la documentation en production
  • Mécanisme d'authentification: Configurer l'authentification pour l'accès à la documentation

Exemple

// Configuration Spring Boot pour désactiver Swagger en production
@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .enable(!environment.acceptsProfiles(Profiles.of("prod")))
            // ... autres configurations
}

3. Tests automatisés

Combinez la documentation et les tests pour garantir que le contenu de la documentation reste cohérent avec le comportement réel de l'API :

Exemple

// Tests Spring Boot avec REST Assured et Swagger
@Test
public void validateSwaggerDocumentation() {
    // Obtenir le JSON Swagger
    String swaggerJson = given()
            .when()
            .get("/v3/api-docs")
            .puis()
            .statusCode(200)
            .extract().asString();
   
    // Vérifier la documentation Swagger
    OpenAPI openAPI = new OpenAPIParser().readContents(swaggerJson, null, null).getOpenAPI();
    assertNotNull(openAPI);
   
    // Vérifier si un endpoint spécifique existe dans la documentation
    assertNotNull(openAPI.getPaths().get("/api/users"));
}

Dépannage des problèmes courants

1. Swagger UI ne s'affiche pas ou erreurs de chargement

  • Vérifier les versions des dépendances: S'assurer que les versions des dépendances sont compatibles
  • Vérifier les classes de configuration: S'assurer que les classes de configuration sont correctement enregistrées
  • Vérifier les mappages de chemins: S'assurer que les mappages de chemins sont corrects
  • Vérifier les paramètres cross-origin: En cas d'accès cross-origin, s'assurer que la configuration CORS est correcte

2. Informations d'API incomplètes

  • Vérifier les annotations: Assurez-vous que toutes les annotations nécessaires ont été ajoutées
  • Vérifier les chemins de scan des packages: Assurez-vous que les chemins de scan incluent tous les contrôleurs
  • Vérifier les classes de modèle: Assurez-vous que les classes de modèle ont des descriptions correctes

3. Problèmes de sécurité dans l'environnement de production

Configurer la production pour désactiver ou protéger la documentation :

# application-prod.properties
springdoc.swagger-ui.enabled=false
springdoc.api-docs.enabled=false

Ou protéger avec une authentification de base :

Exemple

@Configuration
@Profile("prod")
public class SwaggerSecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.requestMatchers()
            .antMatchers("/swagger-ui/**", "/v3/api-docs/**")
            .et()
            .authorizeRequests()
            .anyRequest().hasRole("ADMIN")
            .et()
            .httpBasic();
    }
}
```

Résumé

Swagger UI est un outil puissant de documentation d'API. Avec une configuration et une utilisation appropriées, il peut grandement améliorer l'utilisabilité des API et l'efficacité du développement. Ce tutoriel présente les concepts de base de Swagger UI, les méthodes d'intégration, la rédaction de documentation, la configuration personnalisée, la publication de documentation et les meilleures pratiques, en espérant être utile à votre travail de documentation d'API.

Retenez les points clés suivants :

  1. Choisissez une méthode d'intégration Swagger adaptée à la pile technologique de votre projet
  2. Concevez et rédigez soigneusement les annotations ou commentaires de documentation d'API
  3. Personnalisez l'interface Swagger UI selon vos besoins
  4. Choisissez une méthode de publication de documentation appropriée
  5. Suivez les meilleures pratiques pour garantir l'exactitude et la sécurité de la documentation

En utilisant correctement Swagger UI, vous pouvez fournir une documentation professionnelle et interactive pour votre API, ce qui rend votre API plus facile à comprendre et à utiliser.

Autres extensions