2023年8月1日发(作者：)
什么是swagger，⼀篇带你⼊门⼀、前⾔在前后端分离开发的过程中，前端和后端需要进⾏api对接进⾏交互，就需要⼀个api规范⽂档，⽅便前后端的交互，但api⽂档不能根据代码的变化发⽣实时动态的改变，这样后端修改了接⼝，前端不能及时获取最新的接⼝，导致调⽤出错，需要⼿动维护api⽂档，加⼤了开发的⼯作量和困难，⽽swagger的出现就是为了解决这⼀系列的问题。⼆、swagger的概述swagger是⼀套基于OpenAPI规范构建的开源⼯具，使⽤RestApi1、代码变，⽂档变2、跨语⾔，⽀持多种语⾔3、swagger-ui 呈现出来的是⼀份可交互式的API⽂档，可以直接在⽂档页⾯尝试API的调⽤4、可以将⽂档规范导⼊相关⼯具（postman、soapui），这些⼯具将会为我们⾃动地创建⾃动化测试补充：RestApi格式是根据请求的⽅式决定本次请求的⼀个操作，譬如：get-->读，post-->写（增、删、改），put-->修改，delete-->删除OpenApi与语⾔⽆关，只是⼀种规范，可以使⽤yaml和json格式进⾏编写，这样更利于我们和机器进⾏阅读swagger主要包含了以下三个部分：swagger editor：基于浏览器的编辑器，我们可以使⽤它编写我们OpenApi规范(yaml或者json配置）Swagger UI：他会将我们编写的OpenApi规范呈现为交互式的API⽂档，后⽂我将使⽤浏览器来查看并且操作我们的RestApiSwagger Codegen：它可以通过OpenApi规范定义的任何API⽣成服务器存根和客户端SDK来简化构建过程使⽤swagger就是把相关信息存储在它定义的描述⽂件⾥⾯（yml或json格式），再通过维护这个描述⽂件可以去更新接⼝⽂档，以及⽣成各端代码三、springfox概述使⽤swagger时如果碰见版本更新迭代时，只需要更改swagger的描述⽂件即可，但是在频繁的更新项⽬版本时很多开发⼈员认为即使修改描述⽂件（yml或json⽂件）也是⼀定的⼯作负担，久⽽久之就直接修改代码，⽽不去修改描述⽂件了，这样基于描述⽂件⽣成接⼝⽂档也失去了意义。Marty Pitt编写了⼀个基于spring的组件swagger-springmvc,Spring-fox就是根据这个组件发展⽽来的全新项⽬;Spring-fox是根据代码⽣成接⼝⽂档，所以正常的进⾏更新项⽬版本，修改代码即可，⽽不需要跟随修改描述⽂件(yml或json⽂件）;spring-fox利⽤⾃⾝AOP特性，把swagger集成进来，底层还是Swagger，但是使⽤起来却⽅便很多，所以在实际开发中，都是直接使⽤spring-fox。四、swagger的使⽤1、新建springboot项⽬2、导⼊相关依赖
@GetMapping("/get") public String get() { return "get"; } @PostMapping("/post") public String post() { return "post"; }
@RequestMapping("/hello") public String hello() { return "hello"; }}4.1 swagger的基础信息配置-->config类@Configuration@EnableSwagger2 //开启swagger2,若启动类上添加了该注解，则配置类可以不添加public class SwaggerConfig { // 创建swagger bean @Bean public Docket docket() { // Docket是swagger全局配置对象 // DocumentationType：指定⽂档类型为swagger2 return new Docket(R_2) // swagger信息 .apiInfo(apiInfo()); } // swagger⽂档信息 public ApiInfo apiInfo() { // 作者信息 Contact contact = new Contact( // ⽂档发布者的名称 "iqiuq", // ⽂档发布者的⽹站地址 "/qiuqblogs/", // ⽂档发布者的电⼦邮箱 "qiuyonghui258@" ); return new ApiInfo( // 标题 "iqiuq swagger api", // ⽂档描述 "演好⾃⼰⼈⽣的剧本", // 版本号 "1.0", // 服务组url地址 "urn:tos",
// 作者信息 contact, // 开源组织 "Apache 2.0", // 开源地址 "/licenses/LICENSE-2.0", // 集合 new ArrayList() ); }}4.2 swagger扫描包配置@Configuration@EnableSwagger2 //开启swagger2public class SwaggerConfig { // 创建swagger bean @Bean public Docket docket() { return new Docket(R_2) // swagger信息 .apiInfo(apiInfo()) // swagger 扫描包配置 // select()获取Docket中的选择器，返回ApiSelectorBuilder构造选择器，如扫描扫描包的注解 .select() /** * requestHandlerSelectors：请求处理选择器 * basePackage()：扫描指定包下的所有接⼝ * any()：扫描所有的包 * none()：不扫描 * withClassAnnotation()：扫描指定类上的注解，参数是⼀个注解的放射对象 * withMethodAnnotation()：扫描⽅法上的注解 */ // 指定扫描器扫描的规则（断⾔） .apis(ckage("ller")) /** * pathSelectors：路径选择器，过滤路径 * ang()：选择所有路径 * none()：都不选择 * ant()：选择指定路径 * regex()：正则表达式 */ .paths(("/hello")) .build(); } return new ApiInfo( // 标题 "iqiuq swagger api", // ⽂档描述 "演好⾃⼰⼈⽣的剧本", // 版本号 "1.0", // 服务组url地址 "urn:tos",
// 作者信息 contact, // 开源组织 "Apache 2.0", // 开源地址 "/licenses/LICENSE-2.0", // 集合 new ArrayList() );}4.3 配置是否开启swagger@Configuration@EnableSwagger2 //开启swagger2public class SwaggerConfig { // 创建swagger bean @Bean public Docket docket() { return new Docket(R_2) // swagger信息 .apiInfo(apiInfo()) // 配置是否开启swagger，若为false，则浏览器不能访问 .enable(false); } // swagger⽂档信息 public ApiInfo apiInfo() { // 作者信息 Contact contact = new Contact( "iqiuq", "/qiuqblogs/", "qiuyonghui258@"); return new ApiInfo( "iqiuq swagger api", "演好⾃⼰⼈⽣的剧本", "1.0", "urn:tos", contact, "Apache 2.0", "/licenses/LICENSE-2.0", new ArrayList()); }}需求：开发和测试环境中开启swagger，其他环境不开启@Configuration@EnableSwagger2 //开启swagger2public class SwaggerConfig { // 创建swagger bean @Bean public Docket docket(Environment environment) { // 配置swagger的docket的bean实例 Profiles profiles = ("dev","test"); // 通过sProfiles()判断是否指定的环境中，是，则为true boolean flag = sProfiles(profiles); return new Docket(R_2) .apiInfo(apiInfo()) .enable(flag) .select() .apis(ckage("ller")) .paths(("/hello")) .build(); } // swagger⽂档信息 public ApiInfo apiInfo() { Contact contact = new Contact( "iqiuq", "/qiuqblogs/", "qiuyonghui258@"); return new ApiInfo( "iqiuq swagger api", "演好⾃⼰⼈⽣的剧本", "1.0", "urn:tos",
contact, "Apache 2.0", "/licenses/LICENSE-2.0", new ArrayList()); }}4.3 swagger分组配置每个组就是⼀个docket实例，多个组就是创建多个docket的实例@Configuration@EnableSwagger2 //开启swagger2public class SwaggerConfig { // 创建swagger bean @Bean public Docket docket1(Environment environment) { // 配置swagger的docket的bean实例 Profiles profiles = ("dev","test"); // 通过sProfiles()判断是否指定的环境中，是，则为true boolean flag = sProfiles(profiles); return new Docket(R_2) // swagger信息 .apiInfo(apiInfo()) // 配置是否开启swagger，若为false，则浏览器不能访问 .enable(flag) // 配置组名 .groupName("iqiuq") .select() .apis(ckage("ller")) .paths(("/hello")) .build(); } @Bean public Docket docket2(Environment environment) { Profiles profiles = ("dev","test"); boolean flag = sProfiles(profiles); return new Docket(R_2) .apiInfo(apiInfo()) .enable(flag) .groupName("哈哈哈") .select() .apis(ckage("ller")) .paths(("/hello")) .build(); } @Bean public Docket docket3(Environment environment) { Profiles profiles = ("dev","test"); boolean flag = sProfiles(profiles); return new Docket(R_2) .apiInfo(apiInfo()) .enable(flag) .groupName("嘻嘻嘻") .select() .apis(ckage("ller")) .paths(("/hello")) .build(); } // swagger⽂档信息 public ApiInfo apiInfo() { Contact contact = new Contact( "iqiuq", "/qiuqblogs/", "qiuyonghui258@"); return new ApiInfo( "iqiuq swagger api", "演好⾃⼰⼈⽣的剧本", "1.0", "urn:tos",
contact, "Apache 2.0", "/licenses/LICENSE-2.0", new ArrayList()); }注意：如果你使⽤的是swagger 3.0 你就需要使⽤
2023年8月1日发(作者：)
什么是swagger，⼀篇带你⼊门⼀、前⾔在前后端分离开发的过程中，前端和后端需要进⾏api对接进⾏交互，就需要⼀个api规范⽂档，⽅便前后端的交互，但api⽂档不能根据代码的变化发⽣实时动态的改变，这样后端修改了接⼝，前端不能及时获取最新的接⼝，导致调⽤出错，需要⼿动维护api⽂档，加⼤了开发的⼯作量和困难，⽽swagger的出现就是为了解决这⼀系列的问题。⼆、swagger的概述swagger是⼀套基于OpenAPI规范构建的开源⼯具，使⽤RestApi1、代码变，⽂档变2、跨语⾔，⽀持多种语⾔3、swagger-ui 呈现出来的是⼀份可交互式的API⽂档，可以直接在⽂档页⾯尝试API的调⽤4、可以将⽂档规范导⼊相关⼯具（postman、soapui），这些⼯具将会为我们⾃动地创建⾃动化测试补充：RestApi格式是根据请求的⽅式决定本次请求的⼀个操作，譬如：get-->读，post-->写（增、删、改），put-->修改，delete-->删除OpenApi与语⾔⽆关，只是⼀种规范，可以使⽤yaml和json格式进⾏编写，这样更利于我们和机器进⾏阅读swagger主要包含了以下三个部分：swagger editor：基于浏览器的编辑器，我们可以使⽤它编写我们OpenApi规范(yaml或者json配置）Swagger UI：他会将我们编写的OpenApi规范呈现为交互式的API⽂档，后⽂我将使⽤浏览器来查看并且操作我们的RestApiSwagger Codegen：它可以通过OpenApi规范定义的任何API⽣成服务器存根和客户端SDK来简化构建过程使⽤swagger就是把相关信息存储在它定义的描述⽂件⾥⾯（yml或json格式），再通过维护这个描述⽂件可以去更新接⼝⽂档，以及⽣成各端代码三、springfox概述使⽤swagger时如果碰见版本更新迭代时，只需要更改swagger的描述⽂件即可，但是在频繁的更新项⽬版本时很多开发⼈员认为即使修改描述⽂件（yml或json⽂件）也是⼀定的⼯作负担，久⽽久之就直接修改代码，⽽不去修改描述⽂件了，这样基于描述⽂件⽣成接⼝⽂档也失去了意义。Marty Pitt编写了⼀个基于spring的组件swagger-springmvc,Spring-fox就是根据这个组件发展⽽来的全新项⽬;Spring-fox是根据代码⽣成接⼝⽂档，所以正常的进⾏更新项⽬版本，修改代码即可，⽽不需要跟随修改描述⽂件(yml或json⽂件）;spring-fox利⽤⾃⾝AOP特性，把swagger集成进来，底层还是Swagger，但是使⽤起来却⽅便很多，所以在实际开发中，都是直接使⽤spring-fox。四、swagger的使⽤1、新建springboot项⽬2、导⼊相关依赖
@GetMapping("/get") public String get() { return "get"; } @PostMapping("/post") public String post() { return "post"; }
@RequestMapping("/hello") public String hello() { return "hello"; }}4.1 swagger的基础信息配置-->config类@Configuration@EnableSwagger2 //开启swagger2,若启动类上添加了该注解，则配置类可以不添加public class SwaggerConfig { // 创建swagger bean @Bean public Docket docket() { // Docket是swagger全局配置对象 // DocumentationType：指定⽂档类型为swagger2 return new Docket(R_2) // swagger信息 .apiInfo(apiInfo()); } // swagger⽂档信息 public ApiInfo apiInfo() { // 作者信息 Contact contact = new Contact( // ⽂档发布者的名称 "iqiuq", // ⽂档发布者的⽹站地址 "/qiuqblogs/", // ⽂档发布者的电⼦邮箱 "qiuyonghui258@" ); return new ApiInfo( // 标题 "iqiuq swagger api", // ⽂档描述 "演好⾃⼰⼈⽣的剧本", // 版本号 "1.0", // 服务组url地址 "urn:tos",
// 作者信息 contact, // 开源组织 "Apache 2.0", // 开源地址 "/licenses/LICENSE-2.0", // 集合 new ArrayList() ); }}4.2 swagger扫描包配置@Configuration@EnableSwagger2 //开启swagger2public class SwaggerConfig { // 创建swagger bean @Bean public Docket docket() { return new Docket(R_2) // swagger信息 .apiInfo(apiInfo()) // swagger 扫描包配置 // select()获取Docket中的选择器，返回ApiSelectorBuilder构造选择器，如扫描扫描包的注解 .select() /** * requestHandlerSelectors：请求处理选择器 * basePackage()：扫描指定包下的所有接⼝ * any()：扫描所有的包 * none()：不扫描 * withClassAnnotation()：扫描指定类上的注解，参数是⼀个注解的放射对象 * withMethodAnnotation()：扫描⽅法上的注解 */ // 指定扫描器扫描的规则（断⾔） .apis(ckage("ller")) /** * pathSelectors：路径选择器，过滤路径 * ang()：选择所有路径 * none()：都不选择 * ant()：选择指定路径 * regex()：正则表达式 */ .paths(("/hello")) .build(); } return new ApiInfo( // 标题 "iqiuq swagger api", // ⽂档描述 "演好⾃⼰⼈⽣的剧本", // 版本号 "1.0", // 服务组url地址 "urn:tos",
// 作者信息 contact, // 开源组织 "Apache 2.0", // 开源地址 "/licenses/LICENSE-2.0", // 集合 new ArrayList() );}4.3 配置是否开启swagger@Configuration@EnableSwagger2 //开启swagger2public class SwaggerConfig { // 创建swagger bean @Bean public Docket docket() { return new Docket(R_2) // swagger信息 .apiInfo(apiInfo()) // 配置是否开启swagger，若为false，则浏览器不能访问 .enable(false); } // swagger⽂档信息 public ApiInfo apiInfo() { // 作者信息 Contact contact = new Contact( "iqiuq", "/qiuqblogs/", "qiuyonghui258@"); return new ApiInfo( "iqiuq swagger api", "演好⾃⼰⼈⽣的剧本", "1.0", "urn:tos", contact, "Apache 2.0", "/licenses/LICENSE-2.0", new ArrayList()); }}需求：开发和测试环境中开启swagger，其他环境不开启@Configuration@EnableSwagger2 //开启swagger2public class SwaggerConfig { // 创建swagger bean @Bean public Docket docket(Environment environment) { // 配置swagger的docket的bean实例 Profiles profiles = ("dev","test"); // 通过sProfiles()判断是否指定的环境中，是，则为true boolean flag = sProfiles(profiles); return new Docket(R_2) .apiInfo(apiInfo()) .enable(flag) .select() .apis(ckage("ller")) .paths(("/hello")) .build(); } // swagger⽂档信息 public ApiInfo apiInfo() { Contact contact = new Contact( "iqiuq", "/qiuqblogs/", "qiuyonghui258@"); return new ApiInfo( "iqiuq swagger api", "演好⾃⼰⼈⽣的剧本", "1.0", "urn:tos",
contact, "Apache 2.0", "/licenses/LICENSE-2.0", new ArrayList()); }}4.3 swagger分组配置每个组就是⼀个docket实例，多个组就是创建多个docket的实例@Configuration@EnableSwagger2 //开启swagger2public class SwaggerConfig { // 创建swagger bean @Bean public Docket docket1(Environment environment) { // 配置swagger的docket的bean实例 Profiles profiles = ("dev","test"); // 通过sProfiles()判断是否指定的环境中，是，则为true boolean flag = sProfiles(profiles); return new Docket(R_2) // swagger信息 .apiInfo(apiInfo()) // 配置是否开启swagger，若为false，则浏览器不能访问 .enable(flag) // 配置组名 .groupName("iqiuq") .select() .apis(ckage("ller")) .paths(("/hello")) .build(); } @Bean public Docket docket2(Environment environment) { Profiles profiles = ("dev","test"); boolean flag = sProfiles(profiles); return new Docket(R_2) .apiInfo(apiInfo()) .enable(flag) .groupName("哈哈哈") .select() .apis(ckage("ller")) .paths(("/hello")) .build(); } @Bean public Docket docket3(Environment environment) { Profiles profiles = ("dev","test"); boolean flag = sProfiles(profiles); return new Docket(R_2) .apiInfo(apiInfo()) .enable(flag) .groupName("嘻嘻嘻") .select() .apis(ckage("ller")) .paths(("/hello")) .build(); } // swagger⽂档信息 public ApiInfo apiInfo() { Contact contact = new Contact( "iqiuq", "/qiuqblogs/", "qiuyonghui258@"); return new ApiInfo( "iqiuq swagger api", "演好⾃⼰⼈⽣的剧本", "1.0", "urn:tos",
contact, "Apache 2.0", "/licenses/LICENSE-2.0", new ArrayList()); }注意：如果你使⽤的是swagger 3.0 你就需要使⽤
发布评论