Introduction détaillée à l'utilisation de Swagger dans le développement d'API Java

Swagger est un outil très utile dans le développement d'API Java. Swagger est un framework API open source permettant de décrire, concevoir et générer des services Web RESTful. Il fournit un ensemble d'annotations pour aider les développeurs à décrire les API et les paramètres. Dans cet article, je vais détailler comment utiliser Swagger dans le développement d'API Java.

1. Installer Swagger

Swagger peut être intégré aux projets Java à l'aide de Maven. Vous pouvez ajouter Swagger à votre projet en utilisant les dépendances Maven suivantes :

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

De plus, vous devez ajouter les dépendances suivantes, pour générer l'interface utilisateur Swagger :

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

2. Configuration de Swagger

dans votre application Java, vous devez configurer Swag. Pour ce faire, vous pouvez créer une classe de configuration pour initialiser Swagger :

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

Dans le code ci-dessus, nous avons défini un bean Docket, qui est l'interface principale de Swagger. Nous l'utilisons pour spécifier le type d'API Swagger et le mapper avec l'URL de l'application.

3. Ajouter des annotations Swagger

Vous pouvez désormais ajouter des annotations Swagger dans votre API Java. Voici quelques annotations Swagger couramment utilisées et leurs utilisations :

• @Api : utilisée pour décrire l'intégralité de l'API.
• @ApiOperation : utilisé pour décrire les opérations de l'API.
• @ApiParam : utilisé pour décrire les paramètres de fonctionnement.
• @ApiModel : Attributs du modèle utilisés pour fournir l'API.
• @ApiModelProperty : Propriétés utilisées pour décrire le modèle API.

Ces annotations peuvent être placées sur des classes, des méthodes, des champs et des paramètres de méthode et peuvent fournir des informations sur les commentaires de l'API en utilisant les attributs value et notes.

Par exemple, si vous avez l'extrait de code suivant :

@RestController
@RequestMapping("/users")
public class UserController {
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        // code to get user
    }
}

Vous pouvez utiliser les annotations Swagger pour décrire la méthode getUser :

@RestController
@RequestMapping("/users")
@Api(value="用户管理", tags="用户管理")
public class UserController {
 
    @GetMapping("/{id}")
    @ApiOperation(value="获取用户信息", notes="根据用户ID获取用户信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    public User getUser(@PathVariable Long id) {
        // code to get user
    }
}

Dans le code ci-dessus, nous avons utilisé les annotations @Api et @ApiOperation. L'annotation @Api est utilisée pour décrire l'intégralité de l'API, y compris le nom et l'étiquette. L'annotation @ApiOperation est utilisée pour décrire le nom de l'opération, ainsi que quelques notes sur l'opération.

4. Générer l'interface utilisateur Swagger

Maintenant que votre application Java est configurée avec les annotations Swagger et Swagger, vous pouvez utiliser l'interface utilisateur Swagger pour afficher et tester l'API.

Pour ce faire, vous pouvez ajouter la ligne suivante sous l'annotation @Bean dans la classe SwaggerConfig :

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

    @Bean
    public UiConfiguration uiConfig() {
        return UiConfigurationBuilder.builder()
            .docExpansion(DocExpansion.LIST)
            .build();
    }
}

Cela ajoutera un bean uiConfig() pour configurer l'interface utilisateur de Swagger. En utilisant le code ci-dessus, nous définissons DocExpansion sur LIST afin que toutes les actions soient développées par défaut dans l'interface utilisateur.

5. Lancez l'application

Vous avez maintenant configuré les annotations Swagger et Swagger et généré l'interface utilisateur Swagger dans la classe SwaggerConfig. Vous pouvez lancer l'application à l'aide de la commande suivante :

$ mvn spring-boot:run

Selon les paramètres par défaut de Swagger, vous pouvez accéder à l'interface utilisateur de Swagger depuis le navigateur. Accédez à http://localhost:8080/swagger-ui.html et vous verrez que l'interface utilisateur Swagger affiche déjà votre API.

6. Test de l'API

Enfin, vous pouvez utiliser l'interface utilisateur Swagger pour tester l'API. En cliquant sur le bouton « Essayer », Swagger UI enverra automatiquement une demande à votre API et vous verrez la réponse dans l'interface utilisateur.

Dans cet article, j'ai présenté comment utiliser Swagger dans le développement d'API Java. Grâce à Swagger, vous pouvez facilement décrire et tester votre API, et générer une documentation facile à lire et à utiliser. Si vous êtes un développeur Java, je vous encourage à essayer Swagger pour simplifier le développement et les tests d'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!