号称世界上最流行的API框架
RestFul Api文档在线自动生成工具=》api文档与API定义同步更新
直接运行,可以在线测试API接口
支持多种语言
官网:https://swagger.io/
2.项目中使用Swagger需要的jar包
注意:我这里使用的2.6.5的springboot,只支持3.0.0的swagger
-
swagger2
io.springfox springfox-swagger2 3.0.0 -
swaggerui
io.springfox springfox-swagger-ui 3.0.0 -
springfox
io.springfox springfox-boot-starter 3.0.0
这里我们使用springboot集成swagger
-
新建一个springboot-web项目
-
导入相关依赖
-
编写一个helloworld工程
-
配置swagger 编写一个configure类
import org.springframework.context.annotation.Configuration; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 //开启Swagger2 public class SwaggerConfig { } -
测试运行
2.x版本的swagger访问http://localhost:8080/swagger-ui.html
3.x版本的swagger访问http://localhost:8080/swagger-ui/index.html
3.配置swaggerswagger的bean实例Docket
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
@EnableSwagger2 //开启Swagger2
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("hty","http://localhost:8080","1156388927@qq.com");
return new ApiInfo(
"hty的swagger",
"hty的swagger",
"1.0",
"http://localhost:8080",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
4.swagger配置扫描接口
有一个方法是Docket中的select方法
package com.hty.config;
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.web.bind.annotation.GetMapping;
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
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
//配置了swagger的bean实例
@Bean
public Docket docket(Environment environment){
//设置要显示的swagger环境
Profiles profiles = Profiles.of("dev","test");
//通过environment.acceptsProfiles判断是否出在自己设定的环境当中 我们想要在测试环境中使用 不要再发布环境中使用
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//enable设置swagger是否启动 目前是由外部环境所配置
.enable(flag)
.select()
//RequestHandlerSelectors 配置要扫描接口的方式
//basePackage 指定要扫描的包
//any()扫描全部
//none()不扫描
//withClassAnnotation 扫描类上的注解 参数是一个注解反射对象
//withMethodAnnotation 扫描方法上的注解 参数是一个注解反射对象
.apis(RequestHandlerSelectors.basePackage("com.hty.controller"))
//paths() 过滤什么路径
//ant() 过滤的路径
// .paths(PathSelectors.ant("/hty/**"))
.build();
}
//配置swagger信息 apiInfo
private ApiInfo apiInfo(){
Contact contact = new Contact("hty","http://localhost:8080","1156388927@qq.com");
return new ApiInfo(
"hty的swagger",
"hty的swagger",
"1.0",
"http://localhost:8080",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
5.配置API文档的分组
修改Docket中的groupName属性即可,若要配置多个组,就需要多个Docket
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.web.bind.annotation.GetMapping;
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
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}
@Bean
public Docket docket4(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group4");
}
}
6.给让实体类也让swagger生成api
解决方案就是:在controller中返回一个实体类对象,之后swagger就会在api中的model中生成一个实体类
//只要接口中返回值中存在实体类,就会被扫描到swagger中
@PostMapping(value = "/user")
public User user(){
return new User();
}
7.给实体类加文档注释
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel("用户实体类")//给类加一个api注释
public class User {
@ApiModelProperty("用户名")//给字段加一个api注释
private String name;
@ApiModelProperty("密码")//给字段加一个api注释
private String password;
}
效果
8.给Controller加文档注释//给一个controller的方法加注释
@ApiOperation("Hello控制类")
9.给参数加文档注释
public String hello(@ApiParam("用户名") String username){
return "hello";
}
10.swagger对接口进行测试
有一个try it out按钮
然后设置用户名,设置完成点击execute
就可以看见最终的效果了



