【SpringBoot 实战】整合 swagger2

本贴最后更新于 464 天前,其中的信息可能已经时异事殊

写完接口,你需要写接口文档,一般都是接口文档都是独立的,你需要花个几十分钟写个文档。

使用了 swagger 之后,你只需要加几个配置,然后重启下项目,你的接口文档就形成了。

整体结构

imagepng

pom 配置

需要引入以下 jar 包

<parent>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-parent</artifactId>
	<version>2.1.1.RELEASE</version>
	<relativePath/> <!-- lookup parent from repository -->
</parent>
	
<dependencies>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-web</artifactId>
	</dependency>
	<dependency>
		<groupId>org.projectlombok</groupId>
		<artifactId>lombok</artifactId>
		<optional>true</optional>
	</dependency>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-test</artifactId>
		<scope>test</scope>
	</dependency>
	<!--添加swagger2核心jar -->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
		<version>2.6.1</version>
	</dependency>
	<!--添加Swagger-UI依赖 -->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger-ui</artifactId>
		<version>2.7.0</version>
	</dependency>
</dependencies>

核心代码

在 ChapterSwagger2Application 类中加入注解:

@EnableSwagger2

新增 Swagger2 配置类,主要实现了 swagger 的一些配置;

@Bean
public Docket createRestApi() {
	ParameterBuilder tokenPar = new ParameterBuilder();

	List<Parameter> pars = new ArrayList<Parameter>();
	tokenPar.name("token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
	pars.add(tokenPar.build());

	return new Docket(DocumentationType.SWAGGER_2)
			.apiInfo(apiInfo()).enable(enableSwagger)
			.select()
			.apis(RequestHandlerSelectors.basePackage("com.cimu.swagger.controller"))
			.paths(PathSelectors.any())
			.build()
			.globalOperationParameters(pars);
}

DemoController 类:里面实现了一些实例;

注解说明

@Api:对 controller 类进行描述。比如:名称,描述,标签,权限,是否显示等。
@ApiOperation:对某个方法进行描述。
@ApiImplicitParam:对单个参数进行描述。可以定义参数名称,名称描述,是否必填,参数类型(path、query、body、header、form)等。
@ApiImplicitParams:定义多个@ApiImplicitParam,如:

@ApiImplicitParams({
  @ApiImplicitParam(name = "mobile", value = "手机号", required = true, paramType = "query"),
  @ApiImplicitParam(name = "name", value = "名称", required = true, paramType = "query")
})

@ApiResponse:对返回值进行设置。
@ApiResponses:对多个返回值进行设置,如:

@ApiResponses({
  @ApiResponse(code = 200, message = "返回数据", response = DemoDto.class)
})

@ApiIgnore:可以忽略方法里面的参数,忽略某个方法,可以忽略某个 controller。
@ApiModel:在 model 对象上注解。
@ApiModelProperty:model 里面属性的注解,定义一个属性的描述。

效果展示

imagepng
可以直接在接口文档里面测试接口,
imagepng

更换风格

如果你觉得系统提供的文档不喜欢,或者看起来不方便,那么可以使用开源的一些皮肤。
可以查看 https://www.cnblogs.com/myhappylife/p/9403563.html
具体的使用方法也有。

源码地址

  • B3log

    B3log 是一个开源组织,名字来源于“Bulletin Board Blog”缩写,目标是将独立博客与论坛结合,形成一种新的网络社区体验,详细请看 B3log 构思。目前 B3log 已经开源了多款产品:PipeSoloSymWide 等。

    1146 引用 • 3286 回帖 • 520 关注
  • Swagger

    Swagger 是一款非常流行的 API 开发工具,它遵循 OpenAPI Specification(这是一种通用的、和编程语言无关的 API 描述规范)。Swagger 贯穿整个 API 生命周期,如 API 的设计、编写文档、测试和部署。

    18 引用 • 15 回帖 • 2 关注
  • Spring

    Spring 是一个开源框架,是于 2003 年兴起的一个轻量级的 Java 开发框架,由 Rod Johnson 在其著作《Expert One-On-One J2EE Development and Design》中阐述的部分理念和原型衍生而来。它是为了解决企业应用开发的复杂性而创建的。框架的主要优势之一就是其分层架构,分层架构允许使用者选择使用哪一个组件,同时为 JavaEE 应用程序开发提供集成的框架。

    732 引用 • 1295 回帖 • 710 关注
回帖
请输入回帖内容...