1. 前置技术: Swagger
1.1 Swagger介绍
OpenAPI规范(OpenAPI Specification 简称OAS)是Linux基金会的一个项目,试图通过定义一种用来描述API格式或API定义的语言,来规范RESTful服务开发过程,目前版本是V3.0,并且已经发布并开源在github上。https://github.com/OAI/OpenAPI-Specification
Swagger是全球最大的OpenAPI规范(OAS)API开发工具框架,支持从设计和文档到测试和部署的整个API生命周期的开发。 https://swagger.io
Spring Boot 可以集成Swagger,生成Swagger接口,Spring Boot是Java领域的神器,它是Spring项目下快速构建项目的框架。
总结:Swagger用于生成API接口工具或框架
1.2 Swagger常用注解
在Java类中添加Swagger的注解即可生成Swagger接口,常用Swagger注解如下:
- @ApiImplicitParam属性:
1.3 基于IDEA简单测试
- 修改pom文件:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<parent>
<artifactId>xc_test_parent</artifactId>
<groupId>com.czxy.xuecheng</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>test_swagger</artifactId>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
</dependencies>
</project>
- 编写yml文件,配置端口号:
server:
port: 8089 #服务端口
- 编写启动类:
package com.czxy.xuecheng.swagger;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class SwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class,args);
}
}
- 编写JavaBean:
package com.czxy.xuecheng.swagger.domain;
import lombok.Data;
@Data
public class User {
private Integer uid;
private String username;
private String password;
}
- 编写测试controller:
package com.czxy.xuecheng.swagger.controller;
import com.czxy.xuecheng.swagger.domain.User;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;
@RestController
@RequestMapping("/swagger")
public class SwaggerController {
@GetMapping("/findAll")
public List findAll(){
List<String> list = new ArrayList<>();
list.add("测试1");
list.add("测试2");
return list;
}
@GetMapping("/{id}")
public String findById(@PathVariable String id){
return "查询成功" + id;
}
@PostMapping
public User save(@RequestBody User user){
return user;
}
}
- 页面访问:
2.1 Swagger 入门
2.1.1 Swagger 配置类
package com.czxy.xuecheng.swagger.config;
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;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createApi(){
// 1 确定文档Swagger版本
Docket docket = new Docket(DocumentationType.SWAGGER_2);
// 2 设置 api基本信息
docket.apiInfo( apiInfo() );
// 3 设置自定义加载路径
docket = docket.select()
.apis(RequestHandlerSelectors.basePackage("com.czxy.xuecheng"))
.paths(PathSelectors.any())
.build();
return docket;
}
/**
* swagger-ui显示api基本信息
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("学成网api文档") //标题
.description("学成在线基于Swagger api文档") //描述
.version("1.0") //版本
.build();
}
}
2.1.2 类配置
- 在类上可以使用 @Api设置描述信息
@RestController
@RequestMapping("/demo")
@Api(tags = "入门程序接口",description = "这个Swagger入门程序的接口,提供基本CRUD操作")
public class DemoController {
2.1.3 方法配置
- 方法基本配置
@GetMapping("/findAll")
@ApiOperation("查询所有")
public List findAll(){
- 方法参数
@ApiImplicitParam(name="名称",value="描述",required = 是否必填,paramType = "参数类型",dataType = "数据类型")
//paramType取值
header --> 请求参数的获取:@RequestHeader
query --> 请求参数的获取:@RequestParam
path(用于restful接口)--> 请求参数的获取:@PathVariable
@GetMapping("/{id}")
@ApiOperation("通过id查询详情")
@ApiImplicitParams({
@ApiImplicitParam(name="id",value="唯一编号",required = true,paramType = "path",dataType = "String")
})
public String findById(@PathVariable String id){
2.1.4 JavaBean配置
package com.czxy.xuecheng.swagger.domina;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "User对象",description = "User描述详细信息")
public class User {
@ApiModelProperty(value = "唯一标识",required = true)
private Integer uid;
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
}
2.1.5 响应状态
@PostMapping
@ApiOperation("添加操作")
@ApiResponses({
@ApiResponse(code = 400,message = "参数异常"),
@ApiResponse(code = 500,message = "服务器端异常"),
@ApiResponse(code = 20000,message = "自定义状态码异常")
})
public User save(@RequestBody User user){
2.1.6 设置权限
2.1.6.1 Swagger 配置
package com.czxy.xuecheng.swagger.config;
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.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import java.util.List;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createApi(){
// 1 确定文档Swagger版本
Docket docket = new Docket(DocumentationType.SWAGGER_2);
// 2 设置 api基本信息
docket.apiInfo( apiInfo() );
// 3 设置自定义加载路径
docket = docket.select()
.apis(RequestHandlerSelectors.basePackage("com.czxy.xuecheng"))
.paths(PathSelectors.any())
.build();
//设置权限
docket.securitySchemes(securitySchemes());
docket.securityContexts(securityContexts());
return docket;
}
/**
* swagger-ui显示api基本信息
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("学成网api文档") //标题
.description("学成在线基于Swagger api文档") //描述
.version("1.0") //版本
.build();
}
private List<ApiKey> securitySchemes() {
List<ApiKey> list = new ArrayList<>();
list.add(new ApiKey("Authorization", "Authorization", "header"));
return list;
}
private List<SecurityContext> securityContexts() {
List<SecurityContext> list = new ArrayList<>();
list.add(SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("^(?!auth).*$"))
.build());
return list;
}
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List<SecurityReference> list = new ArrayList();
list.add(new SecurityReference("Authorization", authorizationScopes));
return list;
}
}