前后端分离必备工具：Swagger

最新推荐文章于 2024-06-25 18:36:58 发布

hello星河

最新推荐文章于 2024-06-25 18:36:58 发布

阅读量414

点赞数

本文链接：https://blog.csdn.net/Wn1999/article/details/118493758

版权

这篇博客介绍了如何在前后端分离的开发环境中利用Swagger2来创建和管理API文档。通过添加相关依赖，配置Docket bean，并使用提供的注解（如@Api、@ApiOperation等）对API进行详细描述，开发者可以方便地生成、查看和调用RESTful Web服务的接口。此外，还展示了如何通过PathSelectors来过滤展示的API路径。

摘要由CSDN通过智能技术生成

一、Swagger2介绍

在前后端分离开发中，api文档是最好的沟通方式
Swadger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。

二、Swagger2使用

1、引入pom

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

2、

package com.xzw.mpluscrud.controller;

import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2配置信息
 */
@Configuration
@EnableSwagger2     //启动Swagger2
public class Swagger2Config {

    @Bean
    public Docket webApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                //只显示api路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/api/.*")))
                .build();

    }

    @Bean
    public Docket adminApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi")
                .apiInfo(adminApiInfo())
                .select()
                //只显示admin路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();

    }

    private ApiInfo webApiInfo(){

        return new ApiInfoBuilder()
                .title("网站-API文档")
                .description("本文档描述了网站微服务接口定义")
                .version("1.0")
                .contact(new Contact("atxzw", "http://localhost:8081/", "493211102@qq.com"))
                .build();
    }

    private ApiInfo adminApiInfo(){

        return new ApiInfoBuilder()
                .title("后台管理系统-API文档")
                .description("本文档描述了后台管理系统微服务接口定义")
                .version("1.0")
                .contact(new Contact("atxzw", "http://localhost:8081/", "49321112@qq.com"))
                .build();
    }


}

3、在启动类标注扫描的包

@ComponentScan(basePackages ="com.xzw")

4、访问http://localhost:8081/swagger-ui.html

三、常用注解

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty