Comment utiliser Swagger2 et l'explication des annotations dans le projet SpringBoot

1. Importer la dépendance de coordonnées Swagger

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

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

La version la plus couramment utilisée est 2.9.2

2. Ajouter l'annotation @EnableSwagger2 à la classe de démarrage du printemps

L'annotation @EnableSwagger2 fournie par renard de printemps Peut activer la technologie associée à swagger2. Le programme parcourra tous les types du package et ses sous-packages de la classe actuelle pour trouver les annotations liées à Swagger et personnaliser le document Swagger

3. Démarrez le projet et affichez l'interface swaggerui.html

Cliquez sur essayer pour entrer les paramètres correspondants et afficher les résultats de retour

Quatrièmement, écrivez le fichier de configuration SwaggerConfig

@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Autowired
    private ApplicationContext applicationContext;

    private Contact contact = new Contact("NIUA","localhost:8080/swagger-ui.html", "1053288979@qq.com");

    @Bean
    public Docket createRestApi() {
        ServletContext servletContext = applicationContext.getBean(ServletContext.class);
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(Predicates.not(regex("/error.*")))
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("平台接口 v1.0")
                .description("平台接口")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

@Bean
    public Docket createRestApi() {
        ServletContext servletContext = applicationContext.getBean(ServletContext.class);
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(Predicates.not(regex("/error.*")))
                .build()
                .apiInfo(apiInfo());
    }

Créez un objet de type Docker et utilisez la gestion des conteneurs Spring. Docker est l'objet de configuration global dans Swagger

Utilisez DocumentationType.SWAGGER_2 pour spécifier l'objet de classe de Docket afin de déterminer quelle version est utilisée

apiInfo() : les informations de description du document API, le paramètre est un objet de classe ApiInfo, utilisez bulid() Builder pour créer

private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
               .title("平台接口 v1.0")
               .description("平台接口")
               .contact(contact)
               .version("1.0")
               .build();
   }

Copier après la connexion

contact() : configurez le contenu principal du document swagger, qui est également un objet de classe. L'objet de classe peut avoir jusqu'à trois paramètres, nom de l'éditeur, adresse URL du site Web de l'éditeur du document ( site corporate) , l'adresse email de l'éditeur du document

private Contact contact = new Contact("NIUA","localhost:8080/swagger-ui.html", "1053288979@qq.com");

Copier après la connexion

title() : title description() : description information.version() : version information

correspond au contenu suivant

La méthode de retour ApiSelectorBuilder est select(), utilisé pour obtenir des sélecteurs dans Docker. Construire des sélecteurs. Par exemple, les annotations des packages à analyser

apis() : suivies des règles (Predicate) sous la classe RequestHandlerSelectors, qui stipulent les annotations de ces packages à analyser. La valeur par défaut est les annotations sous la classe de démarrage et ses. sous-packages

Combien y en a-t-il sous la classe RequestHandlerSelectors ? méthodes statiques (trois exemples)

basePackage() : Remplissez plus tard l'adresse spécifique du nom du package, ainsi que les annotations du package modifié et de ses sous-packages sera analysé

docker.apis(RequestHandlerSelectors.basePackage("com.xxx"))

Copier après la connexion

any() : générer de la documentation API pour n'importe quelle interface

none() : aucun document d'interface ne sera généré pour aucune interface

path() : utiliser des expressions régulières pour contraindre l'adresse de chemin de l'API générée document, puis remplissez le chemin filtré (passé)

//过滤掉admin路径下的所有页面
.paths(Predicates.not(PathSelectors.regex("/admin/.*")))
//过滤掉所有error或error.*页面
.paths(Predicates.not(PathSelectors.regex("/error.*")))

//所有error或error.*页面或者admin路径下的所有页面都支持（or任意满足起一就通过）
.paths(Predicates.or(PathSelectors.regex("/error.*"),PathSelectors.regex("/admin/.*")))

Copier après la connexion

Cinq : Swagger prend en charge les annotations personnalisées

ici Ce n'est pas mentionné. Si vous êtes intéressé, vous pouvez le rechercher par vous-même (laissez un espace pour des informations supplémentaires dans le. futur)

Six : annotations communes Swagger2

@Api (couramment utilisé)

Fonction : @Api est une annotation sur la classe. Contrôlez le contenu des informations d'interface générées par l'ensemble de la classe

Attributs :

tags : le nom de la classe. S'il y a plusieurs valeurs, ce qui signifie que plusieurs copies (alias) sont disponibles, la vue SwaggerUI affichera quels contrôleurs le menu est accessible à partir de quels

description : Description, obsolète

@ApiOperation

Fonction : @ApiOperation est une annotation sur la méthode, décrivant les informations pertinentes de la méthode

Attributs :

valeur : fonction de description de la méthode

notes : notes de méthode (développer la description)

@ApiParm

Fonction : @ApiParm est une annotation pour les paramètres de méthode. Décrivez le paramètre

attribut :

nom : nom du paramètre

valeur : décrivez la fonction du paramètre

obligatoire : la valeur est de type booléen, indiquant si le paramètre est un paramètre nécessaire, la valeur par défaut est false

@ApiIgnore

作用：@ApiParm是方法或者参数的注解。忽略注解的方法或者参数，不生成帮助文档

@ApiImplicitParam(常用)

作用：@ApiParm是作用于类上方法，用来描述方法参数的注解。

属性：

name：参数名称，和方法的参数一致

value：参数具体描述

required：值为boolean类型，表示该参数是否为必要参数，默认为false

paramType：参数类型

paramType="字符串"
paramType = "header"

Copier après la connexion

dataType：数据类型

dataType = "string"  //字符串数据
dataType = "键值对"

Copier après la connexion

@ApiImplicitParams

后面跟@ApiImplicitParam的集合，一般用于多个参数的描述

@ApiImplicitParams({@ApiImplicitParam(name = "Authorization", value = "Authorization token", required = true, dataType = "string", paramType = "header")})

@ApiModel(常用)

作用：@ApiModel是作用于实体类上，描述一个实体类型，整个实体类型如果成为任何一个生成api帮助文档的返回对象的时候，该注解被解析

属性：

value：实体类名称

description：实体类描述

@ApiModelProperty(常用)

作用：@ApiModel是作用于实体类的属性上，描述实体类属性

属性：

value：实体属性描述

name：实体类属性名字，与属性名一致

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!