swagger对接
概述
项目采用前后台分离的架构进行开发,后台可以使用Swagger,生成在线API文档,方便前端人员对
接使用
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger官网
配置生成的在线API文档样例:
springfox,是一个开源的API Doc的框架,它的前身是swagger-springmvc,可以将我们的Controller中的方法以文档的形式展现。
springfox-swagger2,它是整合springmvc和swagger2的一个项目,项目中使用swagger时,要引入它的依赖
使用
在springboot中,使用Swagger非常简单,引入依赖,并做出少量的固定配置即可
例如,新建项目springboot-swagger,如下
1.pom文件,引入依赖swagger2的依赖
<?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
https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.4.0</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.briup.demo</groupId>
<artifactId>springboot-swagger</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>springboot-swagger</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- 引入swagger相关依赖 -->
<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>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
2、使用配置类,对swagger进行配置
package com.briup.cms.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;
//开始springboot中对swagger2的支持
@EnableSwagger2
@Configuration
public class Swagger2Config {
//配置需要扫描的Controller的包路径
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.briup.cms.web.controller"))
.paths(PathSelectors.any())
.build();
}
//swagger界面中显示的基本信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("swagger在线API")
.description("欢迎访问briup官网,http://www.briup.com")
.termsOfServiceUrl("http://www.briup.com")
.version("1.0")
.build();
}
}
注意,swagger中基本都是固定的配置,按照自己的项目情况,进行修改字符串变量即可
3、Controller中使用swagger相关注解,进行辅助说明
package com.briup.cms.web.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import com.briup.cms.util.Result;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
@Api(tags = "测试模块")
@RestController
public class HelloController {
@ApiOperation(value = "hello测试",notes = "第一个swagger测试程序")
@ApiImplicitParams({
@ApiImplicitParam(name = "name",value = "用户名",dataType =
"String",required = true,defaultValue = "tom",paramType = "query"),
})
@GetMapping("/hello")
public Result hello(String name) {
if("tom".equals(name)) {
throw new RuntimeException("异常测试...");
}
return Result.success("hello world!"+name);
}
}
其中:
-
@Api ,用来指定当前API模块的名称
-
@ApiOperation ,用来设置API方法的简介说明
-
@ApiImplicitParams ,用来设置API方法的参数,可以有多个参数
-
@ApiImplicitParam ,用来设置一个参数的详细信息
name,参数的名称 value,参数的介绍 dataType,参数的数据类型,例如String required,是否为必须参数 defaultValue,默认填入输入框的值 paramType,参数的类型:path、query、body、header、form
注意,这些注解配置,都是可以不写的,swagger也能自动扫描这个Controller及其处理方法,并生
成文档
4、启动项目,访问固定地址:http://127.0.0.1:8989/swagger-ui.html
此时,就可以使用swagger的在线文档,对Controller中暴露出来的API进行测试了。该项目中其他类,都
是起到辅助作用,对本例中swagger的使用,没有任何影响。具体代码可查看项目实例。
- 点赞
- 收藏
- 关注作者
评论(0)