文档章节

使用SwaggerSpringBootStarter展示web项目api接口

阿信sxq
 阿信sxq
发布于 2017/07/27 15:41
字数 1277
阅读 1865
收藏 3

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

查看

© 著作权归作者所有

共有 人打赏支持
阿信sxq

阿信sxq

粉丝 223
博文 80
码字总数 70802
作品 1
成都
后端工程师
加载中

评论(15)

阿狸粑粑
阿狸粑粑

引用来自“阿信sxq”的评论

引用来自“阿狸粑粑”的评论

误人子弟就是你这种人了

额,哪里有什么不正确的吗,麻烦指出来一下啊,博客里面描述的方式我已经使用一年半多了,没有什么不正确的,如果有什么不正确的,麻烦指出来一下,我也好学习改正啊,先谢谢了

引用来自“阿狸粑粑”的评论

那demo运行根本没用

引用来自“阿信sxq”的评论

之前的那个版本也是正常的,之所以更新版本是我开始没有发现我使用的是java 10,在排除问题的时候更新的版本
态度可以,我收回我之前的评论
阿信sxq
阿信sxq

引用来自“阿信sxq”的评论

引用来自“阿狸粑粑”的评论

误人子弟就是你这种人了

额,哪里有什么不正确的吗,麻烦指出来一下啊,博客里面描述的方式我已经使用一年半多了,没有什么不正确的,如果有什么不正确的,麻烦指出来一下,我也好学习改正啊,先谢谢了

引用来自“阿狸粑粑”的评论

那demo运行根本没用
之前的那个版本也是正常的,之所以更新版本是我开始没有发现我使用的是java 10,在排除问题的时候更新的版本
阿信sxq
阿信sxq

引用来自“阿信sxq”的评论

引用来自“阿狸粑粑”的评论

误人子弟就是你这种人了

额,哪里有什么不正确的吗,麻烦指出来一下啊,博客里面描述的方式我已经使用一年半多了,没有什么不正确的,如果有什么不正确的,麻烦指出来一下,我也好学习改正啊,先谢谢了

引用来自“阿狸粑粑”的评论

那demo运行根本没用
我更新了下版本,现在依赖最新的spring boot版本了,只能使用java 8来运行,我使用10是不能运行的,你看一下。
还有,就算时不能运行,你也不应该直接就评价为“误人子弟”啊,指出问题就行了嘛。
再说一次,我这边使用java 8的环境是可以正常运行、访问的,请检查下环境那些
阿狸粑粑
阿狸粑粑

引用来自“阿信sxq”的评论

引用来自“阿狸粑粑”的评论

误人子弟就是你这种人了

额,哪里有什么不正确的吗,麻烦指出来一下啊,博客里面描述的方式我已经使用一年半多了,没有什么不正确的,如果有什么不正确的,麻烦指出来一下,我也好学习改正啊,先谢谢了
那demo运行根本没用
阿信sxq
阿信sxq

引用来自“阿狸粑粑”的评论

误人子弟就是你这种人了

额,哪里有什么不正确的吗,麻烦指出来一下啊,博客里面描述的方式我已经使用一年半多了,没有什么不正确的,如果有什么不正确的,麻烦指出来一下,我也好学习改正啊,先谢谢了
阿狸粑粑
阿狸粑粑
误人子弟就是你这种人了
阿信sxq
阿信sxq

引用来自“沉浮aim”的评论

在application.properties 中的中文,页面上是乱码 不知道哪里要做处理

引用来自“阿信sxq”的评论

在这个文件中只能存unicode的,中文需要转换,读取出来的才能是正常的,可以去看看Properties类的介绍哦

引用来自“沉浮aim”的评论

之前好像是正常的 ,然后我把编码改成utf8就成乱码了,现在也确实用unicode编码处理的。之前取值的方法都是通过spring提供的ConfigurationProperties注解,按道理应该不会这样,那应该是在浏览器访问界面的时候出的问题

引用来自“阿信sxq”的评论

那你就试试与浏览器无关的检查呗,直接日志记录试试

引用来自“沉浮aim”的评论

竟然从实体里取出来就是乱码了,当然idea 中transparent native-to-ascii conversion勾上就好了,还真是奇怪
你是新手吧
沉浮aim
沉浮aim

引用来自“沉浮aim”的评论

在application.properties 中的中文,页面上是乱码 不知道哪里要做处理

引用来自“阿信sxq”的评论

在这个文件中只能存unicode的,中文需要转换,读取出来的才能是正常的,可以去看看Properties类的介绍哦

引用来自“沉浮aim”的评论

之前好像是正常的 ,然后我把编码改成utf8就成乱码了,现在也确实用unicode编码处理的。之前取值的方法都是通过spring提供的ConfigurationProperties注解,按道理应该不会这样,那应该是在浏览器访问界面的时候出的问题

引用来自“阿信sxq”的评论

那你就试试与浏览器无关的检查呗,直接日志记录试试
竟然从实体里取出来就是乱码了,当然idea 中transparent native-to-ascii conversion勾上就好了,还真是奇怪
阿信sxq
阿信sxq

引用来自“沉浮aim”的评论

在application.properties 中的中文,页面上是乱码 不知道哪里要做处理

引用来自“阿信sxq”的评论

在这个文件中只能存unicode的,中文需要转换,读取出来的才能是正常的,可以去看看Properties类的介绍哦

引用来自“沉浮aim”的评论

之前好像是正常的 ,然后我把编码改成utf8就成乱码了,现在也确实用unicode编码处理的。之前取值的方法都是通过spring提供的ConfigurationProperties注解,按道理应该不会这样,那应该是在浏览器访问界面的时候出的问题
那你就试试与浏览器无关的检查呗,直接日志记录试试
沉浮aim
沉浮aim

引用来自“沉浮aim”的评论

在application.properties 中的中文,页面上是乱码 不知道哪里要做处理

引用来自“阿信sxq”的评论

在这个文件中只能存unicode的,中文需要转换,读取出来的才能是正常的,可以去看看Properties类的介绍哦
之前好像是正常的 ,然后我把编码改成utf8就成乱码了,现在也确实用unicode编码处理的。之前取值的方法都是通过spring提供的ConfigurationProperties注解,按道理应该不会这样,那应该是在浏览器访问界面的时候出的问题
微信小程序结合后台数据管理实现商品数据的动态展示、维护

微信小程序给我们提供了一个很好的开发平台,可以用于展现各种数据和实现丰富的功能,本篇随笔介绍微信小程序结合后台数据管理实现商品数据的动态展示、维护,介绍如何实现商品数据在后台管理...

walb呀
2017/12/04
0
0
在 spring-boot 中使用 swagger--SwaggerSpringBootStarter

在spring-boot中使用swagger,可以实现对代码无侵入地集成swagger 使用时的项目配置 需要在spring boot项目中使用,下面按照使用maven构建项目,以及使用文件来配置进行介绍, 如果使用其他的...

阿信sxq
2017/07/21
342
0
C#开发微信门户及应用(47) - 整合Web API、微信后台管理及前端微信小程序的应用方案

在微信开发中,我一直强调需要建立一个比较统一的Web API接口体系,以便实现数据的集中化,这样我们在常规的Web业务系统,Winform业务系统、微信应用、微信小程序、APP等方面,都可以直接调用...

walb呀
2017/12/04
0
0
使用swagger实现web api在线接口文档

原文:使用swagger实现web api在线接口文档 一、前言   通常我们的项目会包含许多对外的接口,这些接口都需要文档化,标准的接口描述文档需要描述接口的地址、参数、返回值、备注等等;像我...

杰克.陈
2017/12/20
0
0
HTTP 服务器中间件--Restc

restc 是一个 HTTP 服务器中间件,其用于可视化展示请求,调试 RESTful 接口。该项目由饿了么前端团队开源。 挂载 restc 中间件后,访问者无需安装浏览器插件,直接通过浏览器访问接口地址,...

lujjjh
2016/11/24
8.5K
9

没有更多内容

加载失败,请刷新页面

加载更多

Mac OS X下Maven的安装与配置

Mac OS X 安装Maven: 下载 Maven, 并解压到某个目录。例如/Users/robbie/apache-maven-3.3.3 打开Terminal,输入以下命令,设置Maven classpath $ vi ~/.bash_profile 添加下列两行代码,之后...

TonyStarkSir
今天
3
0
关于编程,你的练习是不是有效的?

最近由于工作及Solution项目的影响,我在重新学习DDD和领域建模的一些知识。然后,我突然就想到了这个问题,以及我是怎么做的? 对于我来说,提升技能的项目会有四种: 纯兴趣驱动的项目。即...

问题终结者
今天
3
0
打开eclipse出现an error has occurred see the log file

解决方法: 1,打开eclipse安装目录下的eclipse.ini文件; 2,打开的文本文件最后添加一行 --add-modules=ALL-SYSTEM 3,保存重新打开Eclipse。...

任梁荣
昨天
4
0
搞定Northwind示例数据库,无论哪个版本的SQLServer都受用

Northwind数据库 从这里可以找到突破口: http://social.msdn.microsoft.com/Forums/zh-CN/Vsexpressvb/thread/8490a1c6-9018-40c9-aafb-df9f79d29cde 下面是MSDN: http://msdn2.microsoft......

QQZZFT
昨天
1
0
mysql主从同步,安装配置操作

准备 两台mysql服务,我这里准备了如下: 主库:192.168.176.128 从库:192.168.176.131 如何在Linux上安装mysql服务,请看https://blog.csdn.net/qq_18860653/article/details/80250499 操作...

小致dad
昨天
5
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部