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
- Visualisation: Fournit une interface de documentation API claire et intuitive
- Interactivité: Prend en charge les tests d'API en ligne sans outils supplémentaires
- Mises à jour en temps réel: La documentation est automatiquement mise à jour après les modifications du code
- Normalisation: Basée sur la spécification OpenAPI, garantissant la cohérence
- 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
<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
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.14</version>
</dependency>
Configurer Swagger
Exemple
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.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 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
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 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.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
* 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 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
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
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.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
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
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
# 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
@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
@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
@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 :
- Choisissez une méthode d'intégration Swagger adaptée à la pile technologique de votre projet
- Concevez et rédigez soigneusement les annotations ou commentaires de documentation d'API
- Personnalisez l'interface Swagger UI selon vos besoins
- Choisissez une méthode de publication de documentation appropriée
- 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