本文是用来演示说明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>     <version>1</version>      <parent>         <groupId>org.springframework.boot</groupId>         <artifactId>spring-boot-starter-parent</artifactId>         <version>1.5.4.RELEASE</version>     </parent>      <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>                 <configuration>                     <mainClass>cn.songxinqiang.demo.swagger.BootApplication</mainClass>                     <layout>JAR</layout>                 </configuration>             </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=1.0 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>1.0.0</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的访问支持,这里我的演示项目是把它放在static目录的,就可以直接访问,在实际项目中为了避免干扰正式代码应该是会单独提供的.

这个swagger-ui来自一个webjar,坐标为

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

因为没有单独配置端口,所以访问本机默认端口的地址:http://127.0.0.1:8080/swagger/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基础上进行的,坐标是

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

其中还把他们的swagger-ui的webjar解压来作为演示项目的一部分,感谢他们的付出,起始那个starter并没有做什么工作,只是启动了springfox-swagger而已,所以代码会那么少.

要使用该stater,需要项目必须是spring mvc的web项目,并且控制器需要使用@Controller(相关联的如@RestController一样)和@RequestMapping进行注解.

一旦展示api,那么就是全部api都会进行展示,后续可能会加入筛选条件的配置.

推荐使用profile进行依赖配置,在正式发布打包中不包含该依赖.

6 展示项目的代码

代码已经托管到码云,可以访问

https://git.oschina.net/songxinqiang/SpringBootSwaggerStarter-Demo

查看