使用SwaggerSpringBootStarter展示web项目api接口

2019独角兽企业重金招聘Python工程师标准>>>

本文是用来演示说明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

查看

转载于:https://my.oschina.net/songxinqiang/blog/1490463