💗wei_shuo的个人主页
💫wei_shuo的学习社区
🌐Hello World !
Swagger
Swagger 是一个用于构建、文档化和测试 RESTful API 的开源框架。它可以通过自动生成 API 文档和客户端 SDK,从而简化了 API 的开发和维护工作。Swagger 支持多种编程语言和平台,包括 Java、Python、Node.js 等;Swagger 是一个非常实用的 API 开发和文档化工具,可以大大提高 API 的开发效率和质量
- API 文档自动生成:通过注解和配置文件,Swagger 可以自动生成 API 的文档,包括接口的请求和响应参数、请求方式、返回结果等
- API 测试工具:Swagger 提供了一个基于 Web 的 API 测试工具,可以方便地测试 API 的各种请求和响应结果
- 客户端 SDK 生成:Swagger 可以根据 API 文档自动生成各种客户端 SDK,包括 Java、Python、Node.js 等
- API 视图展示:Swagger 可以将 API 文档以清晰的视图展示出来,方便用户查看和理解 API 的使用方式
Springboot集成Swagger
• 依赖导入
<!--springfox-boot-starter-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<!--springfox-swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
<!--springfox-swagger-ui-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
• controller/SwaggerController.java
package com.wei.config;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
//开启Swagger2
@EnableSwagger2
public class SwaggerConfig {
}
• SpringbootSwaggerApplication.java
package com.wei;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.oas.annotations.EnableOpenApi;
@SpringBootApplication
@EnableWebMvc
@EnableOpenApi
public class SpringbootSwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SpringbootSwaggerApplication.class, args);
}
}
• controller/HelloController.java
package com.wei.controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloController {
@RequestMapping("/hello")
public String hello(){
return "Hello,Swagger!";
}
}
• 浏览器访问:http://localhost:8080/swagger-ui/index.html
配置Swagger信息
• confing/SwaggerConfig.java
package com.wei.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
@Configuration
//开启Swagger2
@EnableSwagger2
public class SwaggerConfig {
//配置Swagger的Bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
//配置Swagger信息apiInfo
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("wei_shuo", "#", "1096075493@qq.com");
return new ApiInfo(
"wei_shuo API文档",
"开源……",
"1.0",
"urn:tos",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
}
• 浏览器运行
配置扫描接口
• confing/SwaggerConfig.java
package com.wei.config;
import com.wei.controller.HelloController;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.RequestHandler;
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;
@Configuration
//开启Swagger2
@EnableSwagger2
public class SwaggerConfig {
//配置Swagger的Bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors 配置要扫描接口的方式
//basePackage("com.wei.controller") 指定扫描包
//.apis(RequestHandlerSelectors.basePackage("com.wei.controller"))
//any() 扫描全部
//.apis(RequestHandlerSelectors.any())
//none() 不扫描
//.apis(RequestHandlerSelectors.none())
//withClassAnnotation() 扫描类注解
//.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
//withMethodAnnotation(GetMapping.class) 扫描方法注解
//.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
.apis(RequestHandlerSelectors.basePackage("com.wei.controller"))
//过滤路径
.paths(PathSelectors.ant("/hello/**"))
.build();
}
//配置Swagger信息apiInfo
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("wei_shuo", "#", "1096075493@qq.com");
return new ApiInfo(
"wei_shuo API文档",
"开源……",
"1.0",
"urn:tos",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
}
• 配置是否启用swagger
//配置Swagger的Bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//是否启用swagger默认true
.enable(false)
.select()
.apis(RequestHandlerSelectors.basePackage("com.wei.controller"))
.build();
}
案例:根据项目环境,配置swagger
- 分别创建properties的开发,测试,发布
• application.properties
spring.profiles.active=dev
#spring.profiles.active=test
#spring.profiles.active=prod
• application-dev.properties
server.port=8081
• application-test.properties
server.port=8082
• application-prod.properties
server.port=8083
• confing/SwaggerConfig.java
package com.wei.config;
import com.wei.controller.HelloController;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.RequestHandler;
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;
@Configuration
//开启Swagger2
@EnableSwagger2
public class SwaggerConfig {
//配置Swagger的Bean实例
@Bean
public Docket docket(Environment environment){
//设置要显示的swagger环境
Profiles profiles = Profiles.of("dev","test","prod");
//通过environment.acceptsProfiles()判断项目环境
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//是否启用swagger默认true
.enable(flag)
.select()
.apis(RequestHandlerSelectors.basePackage("com.wei.controller"))
.build();
}
配置API分组
• API文档分组
//API文档分组
.groupName("wei")package com.wei.config;
import com.wei.controller.HelloController;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.RequestHandler;
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;
@Configuration
//开启Swagger2
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docker1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docker2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docker3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}
//配置Swagger的Bean实例
@Bean
public Docket docket(Environment environment){
//设置要显示的swagger环境
Profiles profiles = Profiles.of("dev","test","prod");
//通过environment.acceptsProfiles()判断项目环境
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//API文档分组
.groupName("wei")
//是否启用swagger默认true
.enable(flag)
.select()
.apis(RequestHandlerSelectors.basePackage("com.wei.controller"))
.build();
}
//配置Swagger信息apiInfo
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("wei_shuo", "#", "1096075493@qq.com");
return new ApiInfo(
"wei_shuo API文档",
"开源……",
"1.0",
"urn:tos",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
}
实体类扫描
• controller/HelloController.java
package com.wei.controller;
import com.wei.pojo.User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello(){
return "Hello,Swagger!";
}
//接口中,返回值存在实体类,就会被扫描到Swagger
@PostMapping("/user")
public User user(){
return new User();
}
}
• pojo/User.java
@Api:描述该类的属性和方法
@ApiModel:描述该类的属性和方法
@ApiModelProperty:描述该属性或方法的作用、类型、格式、是否必需等信息
package com.wei.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
* @ClassName User
* @Description TODO
* @Author wei_shuo
* @Date 2023/5/7 10:55
* @Version 1.0
*/
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
• controller/HelloController.java
package com.wei.controller;
import com.wei.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
@Api(tags = "Hello控制类")
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello() {
return "Hello,Swagger!";
}
//接口中,返回值存在实体类,就会被扫描到Swagger
@PostMapping("/user")
public User user() {
return new User();
}
@ApiOperation("Test控制类")
@GetMapping("/test")
public String test(@ApiParam("用户名") String username) {
return "Hello" + username;
}
}
🌼 结语:创作不易,如果觉得博主的文章赏心悦目,还请——点赞
👍收藏
⭐️评论
📝