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; } }

2.1.7 设置token