Comment utiliser Swagger pour générer de la documentation API ?

Avec le développement rapide des applications Web, la documentation des API devient de plus en plus importante. La documentation de l'API est conçue pour aider les développeurs à comprendre les méthodes et paramètres d'utilisation de l'API, réduisant ainsi la perte de temps et de ressources. Cependant, la rédaction manuelle de la documentation de l'API peut s'avérer fastidieuse et chronophage. À l'heure actuelle, Swagger devient un outil puissant pour les développeurs. Swagger est un outil de documentation API populaire qui peut générer automatiquement une documentation API lisible et interactive. Dans cet article, nous avons présenté comment utiliser Swagger pour générer automatiquement la documentation de l'API.

Qu'est-ce que Swagger ?

Swagger est un ensemble d'outils open source qui aident les développeurs à créer, concevoir, décrire et utiliser des services Web RESTful. Swagger vous permet d'écrire une documentation API à l'aide des formats YAML ou JSON qui décrivent les opérations de l'API et génèrent une documentation d'interface facile à lire et à utiliser.

Swagger prend en charge plusieurs langages et frameworks de programmation tels que Java, C#, Python et Ruby. Il peut également s'intégrer à de nombreux frameworks API existants, notamment Spring, Express et Django, entre autres.

Utiliser Swagger pour générer des documents API nécessite d'abord d'installer l'interface utilisateur Swagger. Swagger UI est un site Web de documentation interactif sur l'API, indépendant de l'API et qui suit la spécification Swagger. Il fournit une belle interface pour visualiser la documentation de l'API et prend en charge les tentatives automatisées d'appels d'API.

Étape 1 : Configurer Swagger

Pour utiliser Swagger, vous devez d'abord télécharger le package Swagger, qui peut être obtenu sur le site Web de Swagger ou téléchargé à l'aide du gestionnaire de dépendances.

Pour configurer l'API Swagger dans le projet Java Spring Boot, vous devez ajouter les dépendances Swagger suivantes dans les dépendances maven :

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${springfox-swagger2.version}</version>
</dependency>
 
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${springfox-swagger-ui.version}</version>
</dependency>

where ${springfox-swagger2.version } et ${springfox -swagger-ui.version} représente le numéro de version de Swagger. Activez swagger dans le fichier de configuration application.properties :

#开启swagger
swagger.enabled = true

Étape 2 : Écrivez des annotations Swagger

Swagger utilise des annotations pour décrire les opérations et les paramètres dans l'API. Ajoutez des annotations Swagger au-dessus de la classe du contrôleur API et de ses méthodes afin que Swagger puisse analyser et générer correctement des documents et les afficher sur l'interface utilisateur de Swagger.

Voici quelques exemples d'annotations :

1. @Api : utilisé pour ajouter des informations de description de l'API

@Api(value="User",tags={"User 操作接口"})
@Controller
@RequestMapping("/users")
public class UserController {
    // ...
}

#🎜🎜 ## 🎜🎜#@ApiOperation : utilisé pour ajouter des informations de description pour les opérations de l'API

2. @ApiOperation(value = "获取用户列表", notes = "")
   @GetMapping(value = "/list")
   public Result getUserList() {
       List<User> userList = userService.listUser();
       return Result.success(userList);
   }

@ApiParam : utilisé pour ajouter des informations de description pour les paramètres de fonctionnement de l'API

# 🎜🎜 #

@ApiOperation(value = "获取用户信息", notes = "根据url的id来获取用户详细信息")
@GetMapping(value = "/{id}")
public Result getUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) {
    User user = userService.getUserById(id);
    return Result.success(user);
}

3. Étape 3 : Démarrez l'application et accédez à Swagger UI

Après avoir terminé la rédaction des annotations Swagger, utilisez un navigateur pour ouvrir l'adresse de Swagger UI. Il crée automatiquement une documentation visuelle sur l'API basée sur votre API.

L'adresse par défaut de Swagger UI est : http://localhost:8080/swagger-ui.html

Sur l'interface de Swagger UI, vous pouvez voir un aperçu de l'interface utilisateur de Swagger. API, descriptions de diverses interfaces API, paramètres de requête et de réponse, ainsi que certains codes de test, etc. Cela peut aider les développeurs à mieux comprendre et utiliser l'API.

Summary

Swagger est un puissant outil de documentation API qui peut générer automatiquement une documentation API facile à lire et avec laquelle interagir. L'utilisation de Swagger peut améliorer l'efficacité et la qualité du développement d'API et réduire le temps et les ressources nécessaires à la rédaction manuelle de la documentation de l'API. En suivant les étapes ci-dessus, vous pouvez facilement commencer à utiliser Swagger pour générer automatiquement la documentation de l'API.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!