最近在学习springboot时候发现好多开源的项目里面都提到了swagger,原来是一个前后端分离开发过程中为了防止两只团队为了需求更改打架,毕竟前端需要加一个参数,后端就要改好多好多,多的不说,直接上货。
1、导入依赖
首先是导入依赖,既然咱是学习就一定要用最新的,才能体现一下咱的实力
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
2、配置
2.1 默认配置
其实是不用配置的,3代版本已经很强了,默认开启swagger,那就写一个controller类直接测试;
链接: http://localhost:8080/swagger-ui/index.html
package com.biubiu.controller;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseBody;
@Controller
public class HomeController {
@GetMapping("/hello")
@ResponseBody
public String hello(){
return "hello,swagger";
}
}
直接成功;
接下来是对一些自己信息的修改
直接上代码
MySwaggerConfig.java
package com.biubiu.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
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
public class MySwaggerConfig {
@Bean
public Docket docket1(){
//这个就是那个组,多了组就多几个docket
return new Docket(DocumentationType.OAS_30).groupName("zhangke");
}
@Bean
public Docket docket(Environment environment){
//获取当前是不是开发环境
Profiles of = Profiles.of("dev", "test");
boolean flag = environment.acceptsProfiles(of);
return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo()).groupName("biubiu").apiInfo(apiInfo())
// .enable(flag)//是否开启swagger
.select()
//RequestHandlerSelectors,配置要扫描接口的方式
//basePackage:指定要扫描的包
//any():扫描全部
//none():不扫描
//wi thClassAnnotation:扫描类上的注解,参数是一个注解的反 射对象
//wi thMethodAnnotation:扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage ("com.biubiu.controller"))//一般不需要,就都直接扫描了
//paths()。过滤什么路径只扫描basepackage里面的什么路径
. paths (PathSelectors.ant( "/*"))
.build();
}
public ApiInfo apiInfo(){
Contact DEFAULT_CONTACT = new Contact("biubiu", "http://www.baidu.com", "2424457802@qq.com");
return new ApiInfo("biubiu的swagger", "一天学会一点点", "v3.0", "http://www.baidu.com"
,DEFAULT_CONTACT , "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
}
}
//需要放行的借口 "/swagger**/**","/webjars/**","/v3/**"
写一个实体类
user.java
package com.biubiu.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@NoArgsConstructor
@AllArgsConstructor
//给实体类加注解
@ApiModel("用户类")
public class User {
//给用户属性加注解
@ApiModelProperty("账号")
private String username;
//给用户属性加注解
@ApiModelProperty("密码")
private String password;
}
控制类代码
controller.java
package com.biubiu.controller;
import com.biubiu.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseBody;
@Controller
public class HomeController {
@GetMapping("/hello")
@ResponseBody
public String hello(){
return "hello,swagger";
}
@ApiOperation("返回user")
@GetMapping("/user")
@ResponseBody
//@ApiParam("用户") 给参数加注解
//@ApiOperation("返回user") 给方法加注解
public User user(@ApiParam("用户") User user){
return user;
}
@ApiOperation("输入参数")
@GetMapping("/name")
@ResponseBody
public String user(@ApiParam("用户名") String name){
return name;
}
}
直接运行
接下来交个大家swagger一些测试;
测试结果200,没有问题
最后是一些注释的作用
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiModelProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用 该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数
@ApiImplicitParam属性:
paramType 查询参数类型
path 以地址的形式提交数据
query 直接跟参数完成自动映射赋值
body 以流的形式提交 仅支持POST
header 参数在request headers 里边提交
form 以form表单的形式提交 仅支持POST
dataType 参数的数据类型 只作为标志说明,并没有实际验证 Long String
name 接收参数名
value 接收参数的意义描述
required 参数是否必填 true 必填 false 非必填
defaultValue 默认值
供大家参考!