Swagger组件—Java最流⾏的API⽂档框架⽂章⽬录
⼀、为什么要⽤Swagger？
前后端分离
前端 -> 前端控制层、视图层
后端 -> 后端控制层、服务层、数据访问层
前后端通过API进⾏交互
前后端相对独⽴且松耦合
产⽣的问题
前后端集成，前端或者后端⽆法做到“及时协商，尽早解决”，最终导致问题集中爆发
解决⽅案
⾸先定义schema ，并实时跟踪最新的API，降低集成风险
⼆、什么是Swagger？
Restful Api ⽂档在线⾃动⽣成器 → API ⽂档 与API 定义同步更新 （ 可以直接运⾏，在线测试API ）三、如何使⽤Swagger？（最简单详细创建步骤）
以SpringBoot框架+Swagger组件为例（JDK1.8及以上）：
Step1：新建⼀个SpringBoot⼯程。
Step2：添加Swagger依赖包。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
<version>2.2.6.RELEASE</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
Step3：添加启动类。
ample.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication; /**
* @description: 启动类
* @author: Create by Liu Wen at 2020-06-13 15:12
**/
@SpringBootApplication
public class SwaggerApplication {
public static void main(String[] args){
SpringApplication.run(SwaggerApplication.class,args);
}
}
Step4：添加Swagger配置（这是最⼩配置）。
fig;
import t.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2; /**
* @description: Swagger配置
* 启动后默认访问：localhost:8080/swagger-ui.html
* @author: Create by Liu Wen at 2020-06-13 15:11
**/
@Configuration//配置类
@EnableSwagger2//开启Swagger2⾃动配置
public class SwaggerConfig {
}
ller;
import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController;
/**
* @description: 测试API接⼝层（即控制层）
* @author: Create by Liu Wen at 2020-06-13 15:12
**/
@RestController
@RequestMapping("/swagger")
public class SwaggerController {
}
Swagger界⾯如下：
Swagger界⾯如下：
四、Swagger进阶配置
Step4：添加Swagger配置（完整配置）
Swagger注解简单说明
@Api(tags = “xxx模块说明”)作⽤在模块类上
@ApiOperation(“xxx接⼝说明”)作⽤在接⼝⽅法上
@ApiModel(“xxxPOJO说明”)作⽤在模型类上：如VO、BO @ApiModelProperty(value = “xxx属性说明”,hidden = true)作⽤在类⽅法和属性上，hidden设置为true可以隐藏该属性@ApiParam(“xxx参数说明”)作⽤在参数、⽅法和字段上，类似@ApiModelProperty
fig;
lemon.base.Predicate;
import org.springframework.beans.factory.annotation.Value;
import t.annotation.Bean;
import t.annotation.Configuration;
import org.springframework.http.ResponseEntity;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import lemon.;
import static springfox.documentation.;
/**
* @description: Swagger配置
* 默认访问：localhost:8080/swagger-ui.html
* @author: Create by Liu Wen at 2020-06-13 15:11
**/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。
* 如何配置多个分组？配置多个分组只需要配置多个Docket即可：
*/
@Bean
public Docket restfulApi(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("RestfulApi")
.genericModelSubstitutes(ResponseEntity.class)
.
useDefaultResponseMessages(true)
.forCodeGeneration(false)
// base，最终调⽤接⼝后会和paths拼接在⼀起
.select()
.paths(doFilteringRules())
.build()
.apiInfo(initApiInfo());
}
private ApiInfo initApiInfo(){
ApiInfo apiInfo =new ApiInfo("XXX项⽬ Platform API",//⼤标题
initContextInfo(),//简单的描述
"1.0.0",//版本
"服务条款",
"后台开发团队",//作者
"The Apache License, Version 2.0",//链接显⽰⽂字
"www.baidu"//⽹站链接
);
return apiInfo;
}
private String initContextInfo(){
StringBuffer sb =new StringBuffer();
sb.append("REST API 设计在细节上有很多⾃⼰独特的需要注意的技巧，并且对开发⼈员在构架设计能⼒上⽐传统 API 有着更⾼的要求。") .append("<br/>")
spring系列框架有哪些.append("本⽂通过翔实的叙述和⼀系列的范例，从整体结构，到局部细节，分析和解读了为了提⾼易⽤性和⾼效性，REST API 设计应该注意哪些问题以及如何解决这些问题。");
String();
}
/**
* 设置过滤规则，这⾥的过滤规则⽀持正则匹配
*/
private Predicate<String>doFilteringRules(){
return or(
regex("/hello.*"),
regex("/vehicles.*")
);
}
}
Step5：添加控制层Controller，⽤于测试。
ller;
import io.swagger.annotations.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ui.ModelMap;
import org.springframework.web.bind.annotation.*;
import ChangedCharSetException;
import java.util.Date;
/
**
* @description: 测试API接⼝层（即控制层）
* @author: Create by Liu Wen at 2020-06-13 15:12
**/
@Api(value ="API - VehiclesController", description ="车辆模块接⼝详情")
@RestController
@RequestMapping("/vehicles")
public class SwaggerController {
private static Logger logger = Logger(SwaggerController.class);
@ApiOperation(value ="查询车辆接⼝", notes ="此接⼝描述xxxxxxxxxxxxx<br/>xxxxxxx<br>值得庆幸的是这⼉⽀持html标签<hr/>", response = String.clas s)
@ApiImplicitParams({
@ApiImplicitParam(name ="vno", value ="车牌", required =false,
dataType ="string", paramType ="query", defaultValue ="辽A12345"),
@ApiImplicitParam(name ="page", value ="page", required =false,
dataType ="Integer", paramType ="query", defaultValue ="1"),
@ApiImplicitParam(name ="count", value ="count", required =false,
dataType ="Integer", paramType ="query", defaultValue ="10")
})
@ApiResponses(value ={
@ApiResponse(code =200, message ="Successful — 请求已完成"),
@ApiResponse(code =400, message ="请求中有语法问题，或不能满⾜请求"),
@ApiResponse(code =401, message ="未授权客户机访问数据"),
@ApiResponse(code =404, message ="服务器不到给定的资源；⽂档不存在"),
@ApiResponse(code =500, message ="服务器不能完成请求")}
)
@ResponseBody
版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。
发表评论