SpringBoot intègre Swagger2 pour générer des documents d'interface. Maman n'a plus à se soucier de l'écriture de documents API.

Dans le processus de développement actuel, les interfaces API sont essentiellement utilisées pour le développement du système. Par conséquent, dans ce processus, un bon document API est devenu le backend et le frontend pour la communication et le développement.

L'approche traditionnelle consiste pour les développeurs à créer un document API RESTful pour enregistrer tous les détails de l'interface. Pour être honnête, la charge de travail n'est pas petite et très triviale, et à mesure que le projet est mis à jour, les problèmes suivants se poseront. se produire.

• La documentation est difficile à maintenir.

• Le contenu de l'interface est plus complexe et l'efficacité d'écriture est moindre.

Swagger est destiné à résoudre ce problème. En tant que framework standardisé et complet, il peut être utilisé pour générer, décrire, appeler et visualiser des services Web de style RESTful :

Via Swagger, nous pouvons générer/mettre à jour automatiquement les documents d'interface API en utilisant des annotations pendant le processus de développement de l'interface et prendre en charge le débogage de l'interface sur la page de documentation.

Ensuite, parlons brièvement de la façon d'intégrer Swagger2 dans SpringBoot (2 représente sa version)

Présentez la dépendance Swagger2

pom.xml fichier

<dependencies>
        <!--Swagger2 在此，个人推荐使用2.8.0版本，较为稳定-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>
</dependencies>

Créer un fichier de configuration

Swagger2Config.javafichier de configuration java

@Configuration
// 指定扫描的api包路径
@ComponentScan(basePackages = {"cn.beatree.xxx.controller"})
//注解开启 swagger2 功能
@EnableSwagger2
public class Swagger2Config {
    @Value("${swagger2.enable}")
    boolean enable;
    // 配置文件中通过值注入控制生产环境与开发环境下的启用状态
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enable)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("ANONVOTE | Swagger API文档")//标题
                .description("description: ANONVOTE | Swagger API文档")//描述
                .contact("BEATREE")//作者信息
                .version("1.0.0")//版本号
                .build();
    }
}

application.ymlFichier de configuration

swagger2:
  enable: false #true 启用

@Configuration, désignée comme classe de configuration, sera chargée au démarrage de SpringBoot.

@EnableSwagger2 annotation pour activer Swagger2.

La méthode membre

createRestApi la fonction crée le Docket Bean, apiInfo() Informations de base utilisées pour créer l'API (ces informations de base seront affichées dans la page de documentation). La fonction select() renvoie un ApiSelectorBuilder L'instance est utilisée pour contrôler quelles interfaces sont exposées à Swagger pour l'affichage. Dans cet exemple, elle est définie en spécifiant le chemin du package analysé. Swagger analysera tous les contrôleurs sous le package. Définit l'API et produit le contenu de la documentation (sauf pour les requêtes spécifiées par @ApiIgnore).

Annotations Swagger couramment utilisées

@Api : modifier la classe entière et décrire le rôle du contrôleur

@ApiOperation : décrit une méthode d'une classe, ou une interface

@ApiParam : décrit un seul paramètre @ApiModel : utilise un objet pour recevoir des paramètres

@ApiProperty : Lorsque vous utilisez un objet pour recevoir des paramètres, décrivez un champ de l'objet

@ApiResponse : Une description de la réponse HTTP

@ApiResponses : La description globale de la réponse HTTP

@ApiIgnore  : Utilisez cette annotation pour ignorer cette API

@ApiError  : Informations renvoyées lorsqu'un une erreur se produit

@ApiImplicitParam : Décrit un paramètre de requête, vous pouvez configurer la signification chinoise du paramètre et vous pouvez également définir la valeur par défaut du paramètre

@ApiImplicitParams : Décrit une liste de paramètres de requête composée de plusieurs

@ApiImplicitParam paramètres annotés

Par exemple

@RestController
@Transactional    // 事务注解，实现回滚
@RequestMapping("/api/tlink")
@Api(value = "/api/tlink", tags = "参与者相关接口")
public class TlinkController{
    @GetMapping("/checkCode/{code}")
    @ApiOperation(value = "投票认证码核验接口",
            notes = "该接口用于核验认证码合法性，对于投票主题内容的获取需后续调用Topic相关接口。返回值data中带有参数 topic & options")
    public JSONObject checkCode(@PathVariable("code") String code){
  ...
 }
}

Enfin, après avoir exécuté le projet SpringBoot, accédez-y via l'adresse du serveur

/swagger-ui.html.

Il convient de noter que si un intercepteur de chemin a été ajouté, le chemin swagger doit être libéré via

.excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**")

.

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!