使用SwaggerSpringBootStarter展示web项目api接口
使用SwaggerSpringBootStarter展示web项目api接口
阿信sxq 发表于9个月前
使用SwaggerSpringBootStarter展示web项目api接口
  • 发表于 9个月前
  • 阅读 1084
  • 收藏 61
  • 点赞 0
  • 评论 3

【腾讯云】新注册用户域名抢购1元起>>>   

摘要: 使用springfox的swagger,配合spring boot来使用,展示web项目的api接口

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

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.5.10.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=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.3</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.8.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.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.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

查看

  • 打赏
  • 点赞
  • 收藏
  • 分享
共有 人打赏支持
阿信sxq
粉丝 208
博文 79
码字总数 69997
作品 1
评论 (3)
hao5ang
不错,一直在用
weifusheng
mark
java9
mark
×
阿信sxq
如果觉得我的文章对您有用,请随意打赏。您的支持将鼓励我继续创作!
* 金额(元)
¥1 ¥5 ¥10 ¥20 其他金额
打赏人
留言
* 支付类型
微信扫码支付
打赏金额:
已支付成功
打赏金额: