Utilisez Spring Boot et Swagger pour créer la documentation de l'API RESTful

Dans le développement Web actuel, l'API RESTful est devenue un moyen très populaire pour les développeurs de créer des sites Web et des applications. Grâce à l'API RESTful, les développeurs peuvent créer des API claires pour interagir plus facilement avec d'autres applications ou services. Afin de mieux gérer et maintenir ces API, la rédaction et la gestion des documents sont également devenues un élément très critique.

Spring Boot est un framework permettant de créer rapidement des applications Java, simple, rapide et facile à développer. Swagger est un outil spécifiquement utilisé pour concevoir, créer et documenter des API RESTful. Il peut générer rapidement des documents API RESTful et générer automatiquement des exemples de flux de demandes et de réponses API.

Cet article explique comment utiliser Spring Boot et Swagger pour créer des documents API RESTful.

1. Créer un projet Spring Boot

Tout d'abord, nous devons utiliser Spring Initializr pour créer un projet Spring Boot, qui peut être créé via https://start.spring.io/. Ici, nous sélectionnons les deux dépendances Web et Swagger 2. Une fois la création terminée, nous importons le projet dans l'environnement de développement intégré et ajoutons la dépendance Swagger dans pom .

Nous ajoutons une méthode dans le Controller :

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

Il est à noter que non seulement l'annotation @RestController doit être ajoutée à la classe, mais également l'annotation @Api doit être utilisée pour décrire le rôle de ce Controller.

Contenu décompilé :

@RestController
public class NumberController {
 
   @ApiOperation(value = "Generate a random number between 1 and 100")
   @RequestMapping(value = "/generateNumber", method = RequestMethod.GET)
   public ResponseEntity<Integer> generateNumber() {
       Random random = new Random();
       int randomNumber = random.nextInt(100) + 1;
       return ResponseEntity.ok(randomNumber);
   }
}

3. Configurer Swagger

Après avoir terminé le développement du contrôleur correspondant, nous devons configurer Swagger. Ajoutez la configuration associée à Swagger au fichier de configuration Spring Boot application.properties.

package com.example.demo.controller;

import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import java.util.Random;

@RestController
public class NumberController
{

    public NumberController()
    {
    }

    @ApiOperation(value="Generate a random number between 1 and 100")
    @RequestMapping(value="/generateNumber", method=RequestMethod.GET)
    public ResponseEntity generateNumber()
    {
        Random random = new Random();
        int randomNumber = random.nextInt(100) + 1;
        return ResponseEntity.ok(new Integer(randomNumber));
    }
}

Description de l'annotation :

@Api : utilisé pour décrire le rôle du contrôleur, similaire aux annotations @Controller et @RequestMapping dans Spring MVC.

@ApiIgnore : utilisé pour les API ignorées et ne sera pas affiché dans la documentation de l'API générée.

@ApiOperation : utilisé pour décrire des opérations API spécifiques, y compris le nom de la méthode, la méthode de requête, les paramètres de requête, l'objet de retour et d'autres informations, qui peuvent être placées sur la méthode ou la classe.

@ApiImplicitParam : utilisé pour décrire les paramètres de la demande, y compris le nom du paramètre, le type de paramètre, la nécessité et d'autres informations.

@ApiModel : utilisé pour décrire les classes JavaBean.

@ApiParam : utilisé pour décrire les informations sur les paramètres.

@ApiResponses : utilisé pour décrire les réponses de l'API, y compris le code d'état HTTP, les données de réponse et d'autres informations.

@ApiProperty : utilisé pour décrire les informations de propriété de la classe JavaBean.

4. Consultez la documentation de l'API

Après avoir terminé la configuration ci-dessus, nous démarrons l'application Spring Boot et visitons http://localhost:8080/swagger-ui.html. Nous pouvons consulter la documentation de l'API générée dans le navigateur. Ici, nous pouvons voir les informations détaillées de l'API que nous venons d'écrire, y compris la méthode de requête, les paramètres de requête, les résultats de retour, etc. Dans le même temps, Swagger peut également générer un exemple de flux de demandes et de réponses pour faciliter la référence et les tests des développeurs.

Ici, nous utilisons Spring Boot et Swagger pour créer la documentation de l'API RESTful. Grâce à cette méthode, les développeurs peuvent créer et gérer leurs propres documents API plus rapidement, améliorant ainsi l'efficacité et la maintenabilité du développement.

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!