Swagger2使用介绍

目录

 使用Swagger

 Swagger配置项

1、构建Docket时通过select()方法配置怎么扫描接口。

 2、根据包的路径扫描接口

3、配置接口扫描过滤

配置Swagger开关

实体配置（不配置也可）

请求的接口配置

常用注解

拓展：其他皮肤

SpringBoot集成Swagger

SpringBoot集成Swagger，springfox，两个jar包

● Springfox-swagger2

● swagger-springmvc

 使用Swagger

1、首先 spring boot 2.6版本以上无法正常使用swagger，我这里使用的2.8.0的版本

2、要求：jdk 1.8 + 否则swagger2无法运行

3、新建一个SpringBoot-web项目

4、添加pom依赖

        io.springfoxspringfox-swagger22.8.0io.springfoxspringfox-swagger-ui2.8.0

5、编写一个配置类-SwaggerConfig来配置 Swagger

package com.example.config;import org.springframework.beans.factory.annotation.Value;
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.builders.RequestHandlerSelectors;
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;import java.util.ArrayList;/*** Swagger2  接口测试工具*/
@Configuration
@EnableSwagger2
public class Swagger2Config {//访问地址：http://localhost:10086/swagger-ui.html@Value("${server.localhost.flag}")private String flag;boolean of = flag.equals("dev");@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2)//方式一、二都可接入.apiInfo(apiInfo())//配置是否启用Swagger，如果是false,在浏览器将无法访问.enable(of)// 通过.select()方法，去配置扫描接口.select()//自行修改为自己项目下的controller路径，RequestHandlerSelectors配置如何扫描接口.apis(RequestHandlerSelectors.basePackage("com.example.controller"))//配置如何通过path过滤，我这里是获取全部.paths(PathSelectors.any()).build();}//方式一private ApiInfo apiInfo1() {return new ApiInfoBuilder().title("swagger-api文档").description("swagger接入教程")//服务条款网址.version("1.0").build();}//方式二private ApiInfo apiInfo() {Contact contact = new Contact("王彦登", "http://localhost:10086/#/", "xxx@163.com");return new ApiInfo("Swagger测试案例", // 标题"学习演示如何配置Swagger", // 描述"v1.0", // 版本"https://blog.csdn.net/m0_59278919?type=collect", // 组织链接contact, // 联系人信息"Apach 2.0", // 许可"https://blog.csdn.net/m0_59278919?type=collect", // 许可连接new ArrayList<>()// 扩展);}
}

6、访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

 Swagger配置项

1、构建Docket时通过select()方法配置怎么扫描接口。

 2、根据包的路径扫描接口

 除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式：

//扫描所有，项目中的所有接口都会被扫描到
any() 
//不扫描接口
none() 
//通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class annotation)
//通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class annotation)
//根据包路径扫描接口
basePackage(final String basePackage) 

3、配置接口扫描过滤

 还可以选择

//任何请求都扫描
any()
/任何请求都不扫描
none()
//通过正则表达式控制
regex(final String pathRegex) 
//通过ant()控制
ant(final String antPattern) 

配置Swagger开关

1、通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了

    @Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2)//方式一、二都可接入.apiInfo(apiInfo())//配置是否启用Swagger，如果是false,在浏览器将无法访问.enable(false)// 通过.select()方法，去配置扫描接口.select()//自行修改为自己项目下的controller路径，RequestHandlerSelectors配置如何扫描接口.apis(RequestHandlerSelectors.basePackage("com.example.controller"))//配置如何通过path过滤，我这里是获取全部.paths(PathSelectors.any()).build();}

2、动态配置当项目处于dev、sit环境时显示swagger

① 在 application.properties中配置环境信息参数

#当前环境
server.localhost.flag=dev

② 通过@Value获取参数，进行参数判断

    // http://localhost:10086/swagger-ui.html#/test-controller@Value("${server.localhost.flag}")private String flag;//动态配置当项目处于dev、sit环境时显示swaggerprivate List cases = Arrays.asList("dev","sit");boolean of = cases.contains(flag);@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2)//方式一、二都可接入.apiInfo(apiInfo())//配置是否启用Swagger，如果是false,在浏览器将无法访问.enable(of)// 通过.select()方法，去配置扫描接口.select()//自行修改为自己项目下的controller路径，RequestHandlerSelectors配置如何扫描接口.apis(RequestHandlerSelectors.basePackage("com.example.controller"))//配置如何通过path过滤，我这里是获取全部.paths(PathSelectors.any()).build();}

实体配置（不配置也可）

1、新建一个实体类

package com.example.pojo;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;@Data
@ApiModel("用户实体")
public class Student {@ApiModelProperty("主键ID")private Integer id;@ApiModelProperty("用户名称")private String studentName;}

2、注解定义

@ApiModel为类添加注释
@ApiModelProperty为类属性添加注释

请求的接口配置

    @RequestMapping(value = "/findAll",method = RequestMethod.GET)//接口的信息描述@ApiOperation(value="查询所有的学生信息", notes="返回的结果中有所有的结果集")public List findAll(){return studentService.findAll();}

常用注解

Swagger的所有注解定义在io.swagger.annotations包下

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

Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。在正式环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运行时内存。

拓展：其他皮肤

1、默认的访问 http://localhost:10086/swagger-ui.html

        io.springfoxspringfox-swagger-ui2.8.0

2、bootstrap-ui 访问 http://localhost:8080/doc.html

        com.github.xiaoyminswagger-bootstrap-ui1.9.1

3、mg-ui 访问 http://localhost:8080/document.html

        com.zyplayerswagger-mg-ui1.0.6

本文来自互联网用户投稿，文章观点仅代表作者本人，不代表本站立场，不承担相关法律责任。如若转载，请注明出处。 如若内容造成侵权/违法违规/事实不符，请点击【内容举报】进行投诉反馈！