Swagger的简单使用

最新推荐文章于 2024-02-21 16:02:47 发布

原创最新推荐文章于 2024-02-21 16:02:47 发布 · 316 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#swagger2 #java

Swagger简介

问题的引入：前后端分离已成为互联网项目开发最流行的使用方式。但是也出现一个问题，即前后端集成联调，前端人员和后端人员无法做到“及时协商，尽早解决”。

解决： Swagger应运而生。

Swagger：

号称世界上最流行的Api框架
RestFul Api文档在线自动生成工具，Api文档与Api定义同步更新
直接运行，可以在线测试Api接口
支持多种语言

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

swagger官网

如何使用Swagger

在项目中使用Swagger需要springfox

SpringBoot集成Swagger

1.新建一个SpringBoot-web项目

2.导入相关依赖

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

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

3.编写一个相关配置类，类上加上注解@Configuration和@EnableSwagger2

@Configuration
@EnableSwagger2  //开启Swagger2
public class SwaggerConfig {

}

此时，Swagger就可以实现最基本的使用了。访问http://localhost:8080/swagger-ui.html 即可查看Swagger的基本页面。

在这里插入图片描述
4. 配置Swagger

Swagger的具体配置

配置Swagger的bean实例Docket

	@Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());//此方法定义Swagger页面的基本信息，不配置则有默认的信息
    }

自定义Swagger页面的基本信息

	protected ApiInfo apiInfo(){
        //配置作者信息
        Contact contact=new Contact("志千","http://zhiqian.site","1270768450");
        return new ApiInfo(
                "志千的SwaggerAPI文档",
                "开始",
                "v1.0",
                "http://zhiqian.site",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()
        );
    }

此时Swagger页面就变成了在这里插入图片描述

Swagger配置扫描接口

在定义Swagger的bean实例Docket时就可以设置扫描条件了。

	//配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//此方法定义Swagger页面的基本信息，不配置则有默认的信息
                .select()
                //RequestHandlerSelectors配置要扫描接口的方式
                .apis(RequestHandlerSelectors.basePackage("com.zhiqian.swagger.controller"))
                //paths() 过滤什么路径,就是路径必须满足条件
                .paths(PathSelectors.ant("/zhiqian/**"))
                .build();
    }

使用链式编程在后面追加select().apis()即可设置扫描接口规则，其中参数为RequestHandlerSelectors，它有很多方法：
1.basePackage()：指定要扫描的包（最常用）
2.any() 扫描全部
3.none() 不扫描
4.withClassAnnotation(xxx.class) ：扫描类上的注解,需要传入注解的class
5.withMethodAnnotation(xxx.class) 扫描方法上的注解，需要传入注解的class
paths()：过滤路径，路径必须满足参数中配置的路径条件才能被扫描

注意：

apis()和paths()必须追加在select()与build()之间。
链式编程后面还可以追加enable()方法来设置是否开启Swagger，默认为true，false表示关闭

配置Api文档的分组

给组命名的方法：

groupName("组名")

该方法追加到.apiInfo()方法的后面即可。
一般我们一个组对应一个Docket的实例。

实体类配置

只要我们的接口中的返回值存在实体类，它就会被扫描到Swagger中

	@PostMapping("/user")
    public User user(){
        return new User();
    }

此时Swagger页面就就存在该实体类了
在这里插入图片描述

我们还可以在实体类上加上@ApiModel注解，在属性上加上@ApiModelProperty注解。
这两个注解的作用是给Swagger页面上对应的实体类加上注释。
在这里插入图片描述
Swagger页面效果：

补充：

我们也可以给Controller类中的方法加上@ApiOperation()注解，给该方法在Swagger页面上加上注释。
可以给Controller类中方法的参数加上@ApiParam()注解，给该参数加上注释

Swagger还拥有测试功能

在这里插入图片描述
点开每个接口，都可以进行测试，可以手动传入接口需要的值。

总结

好处：

可以通过Swagge提供的注解给一些比较难理解的属性或者接口，增加注释信息
接口文档实时更新
可以在线测试

注意：出于安全考虑，在正式发布项目的时候，关闭Swagger！