Spring Boot 教程 (4) - swagger-ui
2020-05-23 16:06:54来源:博客园 阅读 ()
Spring Boot 教程 (4) - swagger-ui
Spring Boot 教程 - swagger-ui
1. 什么是Swagger?
Swagger?的目标是为REST APIs 定义一个标准的,与语言无关的接口,使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义,消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口,Swagger去掉了调用服务时的很多猜测。
浏览 Swagger 去了解更多关于Swagger 项目的信息,包括附加的支持其他语言的库。
2. 在项目中集成Swagger
-
2.1 引入maven依赖
我自己的项目中使用的是swagger2。
<!--springboot父工程--> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.2.2.RELEASE</version> <relativePath/> <!-- lookup parent from repository --> </parent> <dependencies> <!--springboot框架web组件--> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>2.2.2.RELEASE</version> </dependency> <!--swagger-ui组件--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <!--swagger组件--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!--mybatis整合springboot组件--> <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>2.1.0</version> </dependency> <!--mysql数据库连接驱动--> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <version>8.0.18</version> </dependency> <!--lombok组件--> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <version>1.18.10</version> </dependency> </dependencies> <build> <!--springboot的maven插件--> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <configuration> <compilerArgs> <arg>-parameters</arg> </compilerArgs> </configuration> </plugin> </plugins> </build>
-
2.2 Swagger的配置
SwggerConfig.java
:package com.butterflytri.config; import com.google.common.base.Predicates; import io.swagger.annotations.ApiOperation; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Profile; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.ParameterBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.schema.ModelRef; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.service.Parameter; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; import java.util.ArrayList; import java.util.HashSet; import java.util.List; import java.util.Set; /** * @author: WJF * @date: 2020/5/21 * @description: SwaggerConfig */ /** * {@link Configuration}:标志这是一个配置类,在spring boot引导类启动时,会自动加载这个类的配置。 * {@link Profile}:说明加载配置文件 'application.yml' 时加载对应的配置。 * {@link EnableSwagger2}:启用Swagger2的配置。 */ @Configuration @Profile("dev") @EnableSwagger2 public class SwaggerConfig { @Bean public Docket restApi() { Class[] classes = this.getClasses(); Set<String> consumesSet = new HashSet<>(); consumesSet.add("application/x-www-form-urlencoded"); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .globalOperationParameters(parameters()) .ignoredParameterTypes(classes) .forCodeGeneration(true) .consumes(consumesSet) .select() .apis(Predicates.and(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))) .paths(PathSelectors.any()) .build(); } /** * API文档的基本信息 * @return ApiInfo */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("学生管理平台") .description("学生管理平台文档") .termsOfServiceUrl("http://127.0.0.1:8080/butterflytri/swagger-ui.html") .contact(new Contact("wjf", "http://butterflytri.com", "butterflytri@163.com")) .version("2.0") .build(); } /** * Swagger2可以在Swagger2文档中添加参数 * @return List<Parameter> */ private List<Parameter> parameters() { // 添加一个参数butterflytri,参数描述:不死蝶 ParameterBuilder paramBuilder = new ParameterBuilder(); List<Parameter> paramList = new ArrayList<Parameter>(); paramBuilder.name("butterflytri") .description("不死蝶") .modelRef(new ModelRef("string")) .parameterType("header") .required(true) .build(); paramList.add(paramBuilder.build()); return paramList; } /** * 获取class数组 * @return Class[] */ private Class[] getClasses() { return new Class[]{}; } }
-
2.3 控制层
StudentController.java
:package com.butterflytri.controller; import com.butterflytri.entity.Student; import com.butterflytri.service.StudentService; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.*; import javax.annotation.Resource; import java.util.List; /** * @author: WJF * @date: 2020/5/16 * @description: StudentController */ @Api(tags = "学生管理接口") @RestController @RequestMapping("/student") public class StudentController { @Resource private StudentService studentService; /** * GET :请求从服务器获取特定资源。举个例子:GET /student(获取所有学生) * @return List<Student> */ @ApiOperation(value = "查询所有学生", httpMethod = "GET", notes = "查询所有学生") @GetMapping("/student") public List<Student> student() { return studentService.findAll(); } /** * GET :请求从服务器获取特定资源。举个例子:GET /student/1(获取id为1学生) * @param id * @return Student */ @ApiOperation(value = "查询学生详情", httpMethod = "GET", notes = "查询学生详情") @ApiImplicitParam(name = "id", value = "学生id", required = true, paramType = "form", dataTypeClass = Long.class) @GetMapping("/student/{id}") public Student student(@PathVariable("id") Long id) { return studentService.findOne(id); } /** * POST :在服务器上创建一个新的资源。举个例子:POST /student(添加学生) * @param student */ @PostMapping("/student") @ApiOperation(value = "添加学生", httpMethod = "POST", notes = "添加学生") @ApiImplicitParams({ @ApiImplicitParam(name = "studentName", value = "学生姓名", required = true, paramType = "form", dataTypeClass = String.class), @ApiImplicitParam(name = "studentNo", value = "学生学号", required = true, paramType = "form", dataTypeClass = String.class), @ApiImplicitParam(name = "sex", value = "学生性别", required = true, paramType = "form", dataTypeClass = String.class), @ApiImplicitParam(name = "age", value = "学生年龄", required = true, paramType = "form", dataTypeClass = Integer.class) }) public void student(@RequestBody Student student) { studentService.add(student); } /** * PUT :更新服务器上的资源(客户端提供更新后的整个资源)。举个例子:PUT /student/1(更新学号为 1 的学生的所有信息) * @param id */ @PutMapping("/student/{id}") @ApiOperation(value = "根据id修改学生信息(大范围)", httpMethod = "PUT", notes = "根据id修改学生信息") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "学生id", required = true, paramType = "from", dataTypeClass = Long.class), @ApiImplicitParam(name = "studentName", value = "学生姓名", required = true, paramType = "form", dataTypeClass = String.class), @ApiImplicitParam(name = "studentNo", value = "学生学号", required = true, paramType = "form", dataTypeClass = String.class), @ApiImplicitParam(name = "sex", value = "学生性别", required = true, paramType = "form", dataTypeClass = String.class), @ApiImplicitParam(name = "age", value = "学生年龄", required = true, paramType = "form", dataTypeClass = Integer.class) }) public void updateById(@PathVariable("id") Long id, Student student) { studentService.updateAll(id,student); } /** * DELETE :从服务器删除特定的资源。举个例子:DELETE /student/1(删除学号为 1 的学生) * @param id */ @DeleteMapping("/student/{id}") @ApiOperation(value = "根据id删除学生信息", httpMethod = "DELETE", notes = "根据id删除学生信息") @ApiImplicitParam(name = "id", value = "学生id", required = true, paramType = "from", dataTypeClass = Long.class) public void deleteById(@PathVariable("id") Long id) { studentService.delete(id); } /** * PATCH :更新服务器上的资源(客户端提供更改的属性,可以看做作是部分更新),使用的比较少,这里就不举例子了。 * @param id * @param student */ @PatchMapping("/student/{id}") @ApiOperation(value = "根据id修改学生信息(小范围)", httpMethod = "PATCH", notes = "根据id修改学生信息") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "学生id", required = true, paramType = "from", dataTypeClass = Long.class), @ApiImplicitParam(name = "studentName", value = "学生姓名", required = true, paramType = "form", dataTypeClass = String.class), @ApiImplicitParam(name = "studentNo", value = "学生学号", required = true, paramType = "form", dataTypeClass = String.class), @ApiImplicitParam(name = "sex", value = "学生性别", required = true, paramType = "form", dataTypeClass = String.class), @ApiImplicitParam(name = "age", value = "学生年龄", required = true, paramType = "form", dataTypeClass = Integer.class) }) public void updatePart(@PathVariable("id") Long id, Student student) { studentService.updatePart(id,student); } }
这些注解也是很容易理解的,相信各位聪明的技术大牛很快就会使用了。这些注解的具体作用其实看看就懂了,甚至不用去查资料,在这里解释下
@ApiImplicitParam
这个注解的一个属性paramType
,这个属性的取值有以下几种:- header:放在请求头,用于请求头参数的获取。使用
@RequestHeader
,在代码中接收参数。 - query:用于get请求的参数拼接。使用
@RequestParam
,在代码中接收参数。 - path:用于restful接口请求参数的获取。使用
@PathVariable
,在映射地址上接收参数。 - body:放在请求体中,使用
@RequestBody
接收参数。 - form:使用form表单的形式传递参数。
- header:放在请求头,用于请求头参数的获取。使用
-
2.4 Entity
Student.java
:package com.butterflytri.entity; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Getter; import lombok.Setter; import lombok.ToString; import java.io.Serializable; /** * @author: WJF * @date: 2020/5/16 * @description: Student */ @ToString @Getter @Setter @ApiModel("学生Entity") public class Student implements Serializable { @ApiModelProperty("学生id") private Long id; @ApiModelProperty("学生姓名") private String studentName; @ApiModelProperty("学生学号") private String studentNo; @ApiModelProperty("性别") private String sex; @ApiModelProperty("年龄") private Integer age; }
可以使用
@ApiModelProperty
注解来标识每个Entity属性的意思。 -
2.5 运行结果
启动项目,访问
http://127.0.0.1:8080/butterflytri/swagger-ui.html
即可看到下面的页面:点开学生管理接口可以看到
StudentController.java
中写的所有接口方法:点开下面的Models,可以看到Entity中的
Student.java
实体类:再点开查询所有学生这个方法,调用一下这个方法,点击Try it out测试一下方法:
在这里看到了一个参数
butterflytri
,而且还是必传参数,这是因为我在SwaggerConfig.java
这个配置文件类中进行了配置,不清楚的可以往上翻一翻,看看那个配置类。点击了Try it out按钮后,随便给这个参数赋值,反正这个参数没有什么,只是给大家做演示看的。然后点击execute按钮,就可以看到返回结果:
3. 项目地址
本项目传送门:spring-boot-swagger-ui
此教程会一直更新下去,觉得博主写的可以的话,关注一下,也可以更方便下次来学习。
原文链接:https://www.cnblogs.com/Butterfly-Tri/p/12944575.html
如有疑问请与原作者联系
标签:
版权申明:本站文章部分自网络,如有侵权,请联系:west999com@outlook.com
特别注意:本站所有转载文章言论不代表本站观点,本站所提供的摄影照片,插画,设计作品,如需使用,请与原作者联系,版权归原作者所有
- Spring系列.ApplicationContext接口 2020-06-11
- springboot2配置JavaMelody与springMVC配置JavaMelody 2020-06-11
- 给你一份超详细 Spring Boot 知识清单 2020-06-11
- SpringBoot 2.3 整合最新版 ShardingJdbc + Druid + MyBatis 2020-06-11
- 掌握SpringBoot-2.3的容器探针:实战篇 2020-06-11
IDC资讯: 主机资讯 注册资讯 托管资讯 vps资讯 网站建设
网站运营: 建站经验 策划盈利 搜索优化 网站推广 免费资源
网络编程: Asp.Net编程 Asp编程 Php编程 Xml编程 Access Mssql Mysql 其它
服务器技术: Web服务器 Ftp服务器 Mail服务器 Dns服务器 安全防护
软件技巧: 其它软件 Word Excel Powerpoint Ghost Vista QQ空间 QQ FlashGet 迅雷
网页制作: FrontPages Dreamweaver Javascript css photoshop fireworks Flash