文档章节

spring boot 整合swagger2 实现动态生成接口文档

太猪-YJ
 太猪-YJ
发布于 01/08 19:59
字数 2279
阅读 216
收藏 4

背景介绍

在以往的项目开发中,项目的接口文档一般以word的形式,互相传阅。但是具有以下缺点:

1.接口更新了,文档没更新

2.系统版本多,接口版本也很多,不好管理

3.测试接口时,通常会使用postman等,http调试工具,如果接口url写错,或者某个必传参数遗漏,就会导致接口测试失败,比较繁琐。

Swagger有什么用?

swagger是一个流行的API开发框架,这个框架以“开放API声明”(OpenAPI Specification,OAS)为基础, 

对整个API的开发周期都提供了相应的解决方案,是一个非常庞大的项目(包括设计、编码和测试,几乎支持所有语言)。

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。 

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。 

文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

swagger2在系统中的主要作用,就是以注解的方式,侵入接口,动态生成可视化接口文档(swagger-ui)。

整体效果如下:

这里写图片描述

接口详情:

这里写图片描述

我们可以在这个文档中,完成对接口的调用测试。

SpringBoot 与 Swagger2

由于java的强大的注解功能,我们使用SpringBoot来结合Swagger2,在使用起来非常简单. 

由于Spring的流行,Marty Pitt编写了一个基于Spring的组件swagger-springmvc,用于将swagger集成到springmvc中来。

pom文件添加依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>

创建api

@Controller
@RequestMapping("user")
public class UserController {
	@RequestMapping(value = "/hello", method = RequestMethod.GET)
	public String hello() {
		return "hello";
	}
}

创建Swagger2配置类

package com.example.demo.utils;

import org.springframework.beans.factory.annotation.Value;
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
public class SwaggerConfig {
	/**
	 * 可以通过变量设置swagger-ui是否显示,比如测试环境可以暴露api文档,生产环境我们就关闭
	 */
	@Value("${swagger.enable}")
	private boolean enableSwagger;

	/**
	 * 固定写法,设置需要扫描的接口类,一般是controller,或者特定的api类 
	 * enable(enableSwagger)控制接口文档的ui的开关
	 */
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(enableSwagger).select()
				.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any())
				.build();
	}
	/**
	 * 在构建接口文档ui时,可以动态的显示一些我们这里添加的提示信息
	 */
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("springboot利用swagger构建api文档").description("rest api 文档构建利器")
				.termsOfServiceUrl("测试url").contact("taizhu").version("1.0").build();
	}
}

@Configuration // 定义配置类,加入到spring配置中去

以上的三个方法,为固定写法。

给启动类添加注解

@EnableSwagger2 // 开启swagger2注解功能

@ComponentScan(basePackages = { "com.example.demo.controller", "com.example.demo.service",
		"com.example.demo.datasource" })
@EnableAutoConfiguration
@EnableSwagger2
public class Demo1Application {

	public static void main(String[] args) {
		SpringApplication.run(Demo1Application.class, args);
	}

}

这时候,我们启动项目,访问:http://localhost/swagger-ui.html,就可以看到初步的接口API文档啦

 

 

Swagger2 注解使用

我们在UserController中增加一个不用传递参数的接口

@RestController
@RequestMapping(value = "/user", produces = "application/json")
@Api(description = "用户管理")
public class UserController {

	@RequestMapping(value = "/hello", method = RequestMethod.GET)
	public String hello() {
		return "hello";
	}

	ArrayList<User> users = new ArrayList<>();

	@ApiOperation(value = "获取用户列表", notes = "获取所有用户信息")
	@RequestMapping(value = "/getAll", method = RequestMethod.GET)
	public List<User> getAll() {
		users.add(new User(1, "luoji", 23));
		users.add(new User(2, "yewenjie", 24));
		return users;
	}
}

可以在接口文档中看到该接口

可以看到返回结果的字段类型,并且可以测试接口,获取到返回的结果。

但是我们如果想选择性的忽略某个字段,而不是把User类中的所有字段暴露出去呢?别着急,我们可以使用另一个注解:

@ApiModelProperty(hidden = true)

此注解可以作用在字段或者方法上,只要 hidden 属性为 true ,该字段或者方法就不会被生成api文档.

目前我们的ui页面中,接口显示参数的类型,但是没有字段的说明,识别起来很困难,还是不要着急,我们也有办法解决:

@ApiModelProperty(value = "用户名") 

value属性指明了该字段的含义(描述 Description),再次刷新浏览器试试:

如下:
 

package com.example.demo.model;

import io.swagger.annotations.ApiModelProperty;

public class User {
	@ApiModelProperty(hidden = true)
	private int id;
	@ApiModelProperty(value = "用户名")
	private String name;
	@ApiModelProperty(value = "年龄")
	private int age;

	public User() {
		super();
	}

	public User(int id, String name, int age) {
		super();
		this.id = id;
		this.name = name;
		this.age = age;
	}

	public int getId() {
		return id;
	}

	public void setId(int id) {
		this.id = id;
	}

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public int getAge() {
		return age;
	}

	public void setAge(int age) {
		this.age = age;
	}

}

那我们再次查看swagger-ui页面,发现id字段,不在接口文档中暴露了。

这时我们创建一个新的insert接口,用来接收对象类型的参数。

我们可以看到因为之前给实体类添加的@ApiModelProperty(value = "用户名")注解和 @ApiModelProperty(hidden = true)注解生效了。

参数不单提示类型,还有备注,而且不需要对外暴露的参数,也不会暴露出来。

 

此时,我们在创建一个接口,通过url来接收参数:

	@ApiOperation(value = "查询用户", notes = "查询用户信息")
	@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
	@RequestMapping(value = "/query/{id}", method = RequestMethod.GET)
	public Integer query(@PathVariable(value = "id") Integer id) {
		return id;
	}

启动项目。打开swagger-ui页面,测试接口,查看是否返回了传入参数。

OK,接口接收到了页面传入参数,并且正确返回,测试通过。

最后,我们创建一个复杂的参数接口,即要接收url传参,又要接收一个对象类型传参

package com.example.demo.controller;

import java.util.ArrayList;
import java.util.List;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import com.example.demo.model.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

@RestController
@RequestMapping(value = "/user", produces = "application/json")
@Api(description = "用户管理")
public class UserController {

	@RequestMapping(value = "/hello", method = RequestMethod.GET)
	public String hello() {
		return "hello";
	}

	ArrayList<User> users = new ArrayList<>();

	@ApiOperation(value = "获取用户列表", notes = "获取所有用户信息")
	@RequestMapping(value = "/getAll", method = RequestMethod.GET)
	public List<User> getAll() {
		users.add(new User(1, "luoji", 23));
		users.add(new User(2, "yewenjie", 24));
		return users;
	}

	@ApiOperation(value = "新增用户", notes = "新增用户信息")
	@RequestMapping(value = "/insert", method = RequestMethod.GET)
	public User insert(User user) {
		users.add(user);
		return user;
	}

	@ApiOperation(value = "查询用户", notes = "查询用户信息")
	@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
	@RequestMapping(value = "/query/{id}", method = RequestMethod.GET)
	public Integer query(@PathVariable(value = "id") Integer id) {
		return id;
	}

	/**
	 * 根据id修改用户信息
	 * 
	 * @param user
	 * @return
	 */
	@ApiOperation(value = "更新信息", notes = "根据url的id来指定更新用户信息")
	@ApiImplicitParams({
			@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path"),
			@ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User") })
	@RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
	public User update(@PathVariable("id") Integer id, User user) {
		return user;
	}

}

启动项目,打开swagger-ui页面,对新接口进行调用

调用成功!

swagger2中的注解:

swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等,如: 

@ApiIgnore:使用注解忽略该API,不会参与文档生成

@ApiOperation:描述该api,如: @ApiOperation(value=”创建用户”, notes=”根据User对象创建用户”)

请求方法:@RequestMapping(value = “user”, method = RequestMethod.POST)

参数x信息:@ApiImplicitParam(name = “user”, value = “用户详细实体user”, required = true, dataType = “User”)

@Api:修饰整个类,描述Controller的作用

@ApiParam:单个参数描述

@ApiModel:用对象来接收参数

@ApiResponses:HTTP响应整体描述

@ApiProperty:用对象接收参数时,描述对象的一个字段

Swagger2 基本使用(重点加粗显示):

@Api: 描述类/接口的主要用途

@ApiOperation: 描述方法用途

@ApiImplicitParam: 描述方法的参数

@ApiImplicitParams: 描述方法的参数(Multi-Params)

可以在上面 创建用户的方法上添加 @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")试试看.

@ApiParam:请求属性

@ApiIgnore: 忽略某类/方法/参数的文档

注意与 @ApiModelProperty(hidden = true)不同, @ApiIgnore 不能用在模型数据上

@ApiResponse:响应配置

如: @ApiResponse(code = 400, message = "无效的用户信息") ,注意这只是在 生成的Swagger文档上有效,不要和实际的客户端调用搞混了. 
通常我们都是统一JSON返回,用不到这个注解

@ApiResponses:响应集配置

@ResponseHeader: 响应头设置

例如: @ResponseHeader(name=”head1”,description=”response head conf”)

@ApiModelProperty:添加和操作模型属性的数据

Swagger-ui页面的汉化

简单的说,就是spring boot 会优先读取resource下面的静态资源。所以将依赖的swagger-ui的jar包里面的swagger-ui.html,拷贝出来,并放在

src/main/resources/META-INF/resources 路径下,然后在页面中,引入我们另外在下载到本地的汉化版的js文件

这样子,每次在打开swagger-ui.html时,都会打开本地的页面,从而加载本地引入的汉化js,达到汉化效果。

汉化的具体请百度。下面是一个汉化后的效果。

本文转载自:https://blog.csdn.net/itguangit/article/details/78978296

太猪-YJ
粉丝 10
博文 86
码字总数 81134
作品 0
海淀
私信 提问
加载中

评论(1)

盗梦年华
使用了一次后发现项目启动时间增加一半不止,如果涉及关联关系,可能导致项目启动卡死…
SpringBoot接口文档自动生成

由于Spring Boot能够快速开发、便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因,这些终端会共用很多底层业...

chcvn
2018/04/10
0
0
SpringCloudSpringBoot使用Swagger2构建强大的RESTful API文档

由于Spring Boot能够快速开发、便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因,这些终端会共用很多底层业...

itcloud
2018/08/15
0
0
SpringBoot整合Swagger2实践

版权声明:本文为博主原创文章,欢迎大家讨论,未经博主允许不得转载. https://blog.csdn.net/u010398771/article/details/88944880 关于 Swagger Swagger能成为最受欢迎的REST APIs文档生成工...

长河
04/01
0
0
使用Swagger2构建Spring Boot RESTful AIP 文档

上一篇我们介绍了如何使用Spring Boot快速构建RESTful API “Spring Boot与RESTful API ” ,本篇则介绍一个配合Spring Boot快速构建RESTful文档的工具 由于Spring Boot具有快速开发、便捷部...

老虎是个蛋蛋
2016/12/23
1K
5
Spring Boot中使用Swagger2生成RESTful API文档(转)

效果如下图所示: 添加Swagger2依赖 在中加入Swagger2的依赖 注意:如果是2.2版本的,有可能在右下角会出现错误,那么请升级为2.7版本的即可解决这个问题。 创建Swagger2配置类 在同级创建S...

easonjim
2017/09/13
0
0

没有更多内容

加载失败,请刷新页面

加载更多

Quartz原理解析

Quartz原理解析 最近项目中好多地方都需要用到定时器,一开始用的是netty的hashWheel,后来发现删除任务的时候不是很好删除,于是就放弃了,然后选择了Quartz。 hashWheel定时器和Quartz的区...

石日天
54分钟前
2
0
explain详解

EXPLAIN列的解释 table 显示这一行的数据是关于哪张表的 type 这是重要的列,显示连接使用了何种类型。从最好到最差的连接类型为 const(读常量,最多只会有一条记录匹配,由于是常量,实际上...

周慕云
57分钟前
1
0
Oracle 修改或新增数据后查不到数据

修改或新增数据后数据库中SQL能查到但执行程序却查不到 因为AutoCommit is OFF 所以 每次新增或修改数据后都要commit 一下,不然只是post edit 的话,执行程序能查到的只是未更新的数据。...

南风末
今天
4
0
python学习整理(1)

#!/usr/bin/env python # -*- conding:utf-8 -*- 1、 python运算: + - * / % ** // In [21]: print(int(1.2)+3) 4 In [22]: print(float(1.2)+3) 4.2 In [15]: print(11//5) 2 In [16]: prin......

芬野de博客
今天
3
0
maven 在无法连接仓库的单机环境下打包程序

前提:依赖的jar已经在本机。 方法:以ojdbc6-11.2.0.4.jar 为例,进入.m2\repository\com\oracle\jdbc\ojdbc6\11.2.0.4 目录,编辑_remote.repositories文件,改写如下: ojdbc6-11.2.0.4....

jingshishengxu
今天
3
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部