Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。
作用:
- 接口的文档在线自动生成。
- 功能测试。
配置
第一步:配置pom.xml
<dependencies>
...
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
<!-- swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>
</dependencies>
第二步:IDEA执行Reimport All Maven Projects
第三步:使用注解来进行启动swagger
package com.template.swagger;
import springfox.documentation.service.Contact;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Created by bianxh on 2019/1/21.
*/
@Configuration
@EnableSwagger2
public class SwaggerApp {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//为当前包路径
.apis(RequestHandlerSelectors.basePackage("com.template.controller"))
.paths(PathSelectors.any())
.build();
// return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
}
//构建 api文档的详细信息函数,注意这里的注解引用的是哪个
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("Spring Boot 使用 Swagger2 构建RESTful API")
//创建人
.contact(new Contact("Bryan", "http://blog.bianxh.top/", ""))
//版本号
.version("1.0")
//描述
.description("API 描述")
.build();
}
}
第四步:配置Controller
package com.template.controller;
/**
* @Description:
* @Author: Bryan
* @Date: 2018/12/29 18:15
*/
@Api(description = "用户操作接口")
@Controller("user")
@RequestMapping("/user")
public class UserController extends BaseController {
//...
@ApiOperation(value = "获取otp", notes="通过手机号获取OTP验证码")
@ApiImplicitParam(name = "telephone", value = "电话号码", paramType = "query", required = true, dataType = "Integer")
@RequestMapping(value = "getotp", method=RequestMethod.GET)
@ResponseBody
public CommonReturnType getOtp(@RequestParam(name = "telephone") String telphone) {
//需要按照一定的规则生成OTP验证码
Random random = new Random();
int randomInt = random.nextInt(99999);
randomInt += 10000;
String otpCode = String.valueOf(randomInt);
//将OTP验证码同对应用户的手机号关,使用httpsession的方式绑定他的手机号与OTPCode
httpServletRequest.getSession().setAttribute(telphone,otpCode);
//将OTP验证码通过短信通道发送给用户,省略
System.out.println("telphone = " + telphone + "& otpCode = " + otpCode);
OtpVo otpVo = new OtpVo();
otpVo.setTelephone(telphone);
otpVo.setOtpCode(otpCode);
return CommonReturnType.create(otpVo);
}
//...
}
第五步:访问 http://localhost:8081/swagger-ui.html,可以看到如下效果
接下来测试一下接口:
后记
使用lombok
lombok简介
Lombok想要解决了的是在我们实体Bean中大量的Getter/Setter方法,以及toString, hashCode等可能不会用到,但是某些时候仍然需要复写,以期方便使用的方法;在使用Lombok之后,将由其来自动帮你实现代码生成,注意,其是 在运行过程中,帮你自动生成的 。就是说,将极大减少你的代码总量。
lombok作用
消除模板代码:getter、setter、构造器、toString()、equals()
便捷的生成比较复杂的代码,例如一个POJO要转化成构建器模式的形式,只需要一个注解。
pom.xml引用方式:
<!-- https://mvnrepository.com/artifact/org.projectlombok/lombok -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.4</version>
<scope>provided</scope>
</dependency>
Swagger Parameter Types
@Apiimplicitparam的paramType的一些资料:https://swagger.io/docs/specification/describing-parameters/
OpenAPI 3.0 distinguishes between the following parameter types based on the parameter location. The location is determined by the parameter’s
in
key, for example,in: query
orin: path
.
- path parameters, such as
/users/{id}
- query parameters, such as
/users?role=admin
- header parameters, such as
X-MyHeader: Value
- cookie parameters, which are passed in the
Cookie
header, such asCookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCU