本文是用来演示说明SwaggerSpringBootStarter的使用的,同时介绍一种方便的展示项目api的方式。
0 项目要求
必须是spring boot的项目,而且需要使用spring mvc,控制器使用@Controller(关联的如@RestController也算)和@RequestMapping进行注解配置。
1 特别说明
使用此方法暴露的接口是所有的接口,没有分组,也没有过滤/选择那些,这个其实没有什么问题,正式的部署也不会使用这个来展示api,本来就是开发过程中的一个工具。
需要单独准备swagger-ui,在本演示项目的工程代码里面有,可以拷贝出去使用。
2 搭建一个spring boot项目
先搭建一个简单的spring boot项目,使用Spring MVC,具体代码可以在这里查看,下面摘要重要代码
缩水版pom.xml
<groupId>cn.songxinqiang</groupId>
<artifactId>swagger-spring-boot-starter-demo</artifactId>
<packaging>jar</packaging>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.0.5.RELEASE</version>
</parent>
<properties>
<java.version>1.8</java.version>
<start-class>cn.songxinqiang.demo.swagger.BootApplication</start-class>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
启动类
@SpringBootApplication
public class BootApplication {
public static void main(String[] args) {
SpringApplication.run(BootApplication.class, args);
}
}
控制器
@RestController
@RequestMapping("/welcome")
public class HelloController {
@RequestMapping(value = "/hello", method = RequestMethod.GET)
public String hello() {
return "hello";
}
@RequestMapping(value = "/user", method = RequestMethod.POST)
public User userInfo(@RequestBody User user) {
user.setPassword("test");
return user;
}
}
实体类
public class User {
private String username;
private String password;
//set,get
}
这个项目的代码非常简单,用过spring boot和Spring MVC的人一看变动,就不单独说明了。
3 加入SwaggerSpringBootStarter
在application.properties中加入api的信息
#配置swagger的api信息
swagger.api.name=demo
swagger.api.title=Demo API
swagger.api.description=SwaggerSpringBootStarter 使用样例,一切就是这么简单
swagger.api.version=2.0.5.RELEASE
swagger.api.contactUser=阿信sxq
swagger.api.contactUrl=https://my.oschina.net/songxinqiang
swagger.api.contactEmail=songxinqiang@vip.qq.com
在pom.xml中加入依赖
<profiles>
<profile>
<id>develop</id>
<dependencies>
<dependency>
<groupId>cn.songxinqiang</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>2.0.5.RELEASE</version>
</dependency>
<dependency>
<groupId>cn.songxinqiang</groupId>
<artifactId>swagger-spring-boot-starter-ui</artifactId>
<version>2.0.5.RELEASE</version>
</dependency>
</dependencies>
</profile>
</profiles>
这里使用一个profile来配置,这样不管里面引入了什么依赖,在使用IDE编写代码的时候都不会有什么影响(比如导入包,我在eclipse上是这样的),而且非常便于打包时通过参数控制不引入这个依赖,便于发布正式包和测试包。
使用上面的配置之后,如果打包使用
mvn clean package
则是打包正式包,不会包含SwaggerSpringBootStarter,也就不会有api展示。
如果使用
mvn clean package -P develop
则会包含SwaggerSpringBootStarter的依赖,项目运行起来之后会有api的展示控制器监听。
4 使用演示
启动项目,使用命令
mvn clean spring-boot:run -P develop
也可以打包之后再运行,效果一样的。
可以单独使用http服务器为浏览器提供swagger-ui的访问支持,这里我的演示项目是把它直接添加在依赖中的
因为没有单独配置端口,所以访问本机默认端口的地址:http://127.0.0.1:8080/swagger-ui.html
这个时候会提示出错,那是因为swagger-ui默认会直接在其页面当前所在的相对路径下寻找服务接口,自然是找不到的,弹出框就是在说明这个情况,并且指导我们填写正确的地址,这里我们把默认填写的地址的后面部分去掉即可,让其从地址:http://127.0.0.1:8080,来获取配置即可。
获取到的展示效果如下
还可以在页面上对api进行测试。
通过具体的控制台查看,可以知道,swagger-ui获取api接口的请求地址是访问的
http://127.0.0.1:8080/v2/api-docs?group=demo
获取到的是一个json数据,里面描述了所有接口的信息,同样也可以在其他可以使用的地方
5 补充说明
整理这个swagger spring boot starter是在springfox提供的springfox-swagger2基础上进行的,ui使用了比较早先的版本,新版本样式改变比较大,如果喜欢,可以使用他们原始的ui来替换我这个ui,坐标分别是
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- 下面这个就是ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
感谢他们的付出,其实这个starter并没有做什么工作,只是启动了springfox-swagger而已,所以代码会那么少。
要使用该stater,需要项目必须是spring mvc的web项目,并且控制器需要使用@Controller(相关联的如@RestController一样)和@RequestMapping进行注解。
一旦展示api,那么就是全部api都会进行展示,后续可能会加入筛选条件的配置。
推荐使用profile进行依赖配置,在正式发布打包中不包含该依赖。
6 展示项目的代码
代码已经托管到码云,可以访问
https://gitee.com/songxinqiang/SpringBootSwaggerStarter-Demo
以及 https://gitee.com/songxinqiang/SpringBootSwaggerStarter-UI
查看