Le projet SpringBoot intègre Swagger et swagger-bootstrap-ui et quelles sont les annotations communes ?

1. Introduction

Avec la popularité de la séparation front-end et back-end dans les projets Internet, le front-end et le back-end sont développés par du personnel différent, et les coûts de communication du projet augmentent également.

Principalement reflété dans la communication des interfaces WebAPI, Swagger2 a vu le jour. Il peut générer dynamiquement des documents d'interface Api, réduire les coûts de communication et promouvoir un développement de projet efficace.

Ce qui suit traite de l'intégration de Swagger2 et swagger-bootstrap-ui sur SpringBoot

2 L'intégration du projet SpringBoot avec swagger

1 Introduire les dépendances

        <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>

2 Écrire les fichiers de configuration

Peut être comparé et modifié en conséquence

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
@Profile({"dev","test"})
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("") //指定分组，对应(/v2/api-docs?group=)
                .pathMapping("") //base地址，最终会拼接Controller中的地址
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
				// .apis(RequestHandlerSelectors.any())
                .apis(RequestHandlerSelectors.basePackage("com.riskeys.sd.custom"))
                .paths(PathSelectors.any())
                .build();
    }

    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("XXX API对接文档")
                .description("XX API对接文档") //描述
                //创建人
                .contact(new Contact("yuhei001", "https://blog.csdn.net/Yuhei0", "18616591658@163.com"))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}

.

3 . Démarrez la page d'accès

http://127.0.0.1:10086/swagger-ui.html

3. Le projet SpringBoot intègre swagger-bootstrap-ui

Effectuez les opérations suivantes en fonction de l'étape 2

.

1 .Introduire les dépendances

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

2. Configurer les règles de traitement des ressources

Si elles ne sont pas configurées, il est possible de signaler l'erreur .9996 lors de l'accès.

Implémentez l'interface WebMvcConfigurer ou WebMvcConfigurationSupport (ancienne version de SpringBoot), implémentez la méthode addResourceHandlers et ajoutez le code ci-dessous.

@Configuration
public class AppWebConfig extends WebMvcConfigurationSupport{

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解决 doc.html 404 报错
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

ou

@Configuration
public class AppWebConfig extends WebMvcConfigurationSupport{
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解决 doc.html 404 报错
        registry.addResourceHandler("doc.html").addResourceLocations("classpath*:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath*:/META-INF/resources/webjars/");
    }
}

De plus, vous pouvez également implémenter la réécriture sur la classe de démarrage

@SpringBootApplication
public class XXXApplication  implements WebMvcConfigurer{
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath*:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath*:/META-INF/resources/webjars/");
    }
}

3 Démarrez la page d'accès

Visitez http://127.0.0.1:10086/doc.html, par rapport à swagger-ui. . En termes de HTML, ce document est plus propre.

4. Introduction aux annotations communes de Swagger

swagger génère des documents d'interface via des annotations, y compris les noms d'interface, les méthodes de requête, les paramètres, les informations de retour, etc.

1. Annotations swagger associées dans Swagger2Config

1.1 @EnableSwagger2 Activer Swagger

Agit sur la classe de configuration ou la classe de démarrage

1.2 @EnableSwaggerBootstrapUI Activer les améliorations de SwaggerBootstrapUi

Act s sur la classe de configuration ou la classe de démarrage, si not Pour utiliser la fonction améliorée, il n'est pas nécessaire de l'activer.

2. Annotations swagger associées dans le contrôleur

2.1 @Api : modifiez la classe entière et décrivez le rôle du contrôleur

la valeur et les balises sont des instructions, les balises peuvent être utilisées à la place de la valeur

@Api(value = "保险公司列表查询", tags = {"保险公司列表查询"})

2.2 @ApiOperation( ) est utilisé Méthode ; représente le fonctionnement d'une requête http

@ApiOperation(value = "信息员保存(注册)/更新", tags = {"信息員保存"}, notes = "messenger desc")

2.3 @ApiParam Utilisé pour les méthodes, les paramètres, les descriptions de champs ; représente l'ajout de métadonnées aux paramètres (description ou si elle est requise, etc.)

S'applique à un seul paramètre

@ApiParam(name="sdMessengerInfo",value="参数描述",required=true)

2.4 Annotations des paramètres de requête, qui peuvent être combinées

• @ApiImplicitParams Utilisé pour les méthodes contenant plusieurs @ApiImplicitParams

• @ApiImplicitParam Utilisé pour les méthodes, représentant une requête individuelle paramètres

Convient à plusieurs paramètres décrits

Exemple :

// 组合使用
@ApiImplicitParams ({
    @ApiImplicitParam(name = "id", value = "参数中文描述", required = true)
})
// 单独使用
@ApiImplicitParam(paramType="query", name="id", dataType="String", required=true, value="参数描述")

Notez que lorsque @ApiParam et @ApiImplicitParam existent en même temps, la description de @ApiImplicitParam prévaudra.

2.5 @ApiIgnore() Utilisé sur des classes ou des méthodes, il n'a pas besoin d'être affiché sur la page par swagger, et est rarement utilisé.

2.6 Configuration de la réponse

• @ApiResponses

• @ApiResponse

// 单独配置
@ApiResponse(code = 400, message = "Invalid user supplied")
// 组合使用
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

2.7 @ResponseHeader Paramètres d'en-tête de réponse

@ResponseHeader(name="head1",description="response head conf")

3. Annotations fanfaronnes associées dans Model

3.1 @ApiModel Utilisé pour les classes ; il représente une description de la classe et est utilisé pour recevoir des paramètres à l'aide de classes d'entités.

@ApiModel(value = "demo", description = "对象描述")

En général, la valeur et la description peuvent être omises

3.2 @ApiModelProperty Utilisé pour les méthodes et les champs ; indique la description des propriétés du modèle ou des modifications apportées aux opérations de données

@ApiModelProperty(value = "用户id",name = "openid2",dataType = "String", required = true, hidden = true)

• valeur – champ Description value–字段说明

• name–重写属性名字

• dataType–重写属性类型

• required–是否必填

• example–举例说明

• hidden

name–Réécrire le nom de l'attribut

🎜🎜dataType–Réécrire le type d'attribut🎜🎜🎜🎜obligatoire&ndash ; obligatoire ? 🎜🎜🎜🎜exemple–Exemple 🎜🎜🎜🎜caché–Masquer🎜🎜🎜🎜 Généralement, seules les valeurs et les valeurs obligatoires sont marquées. 🎜

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!