文档章节

使用SwaggerSpringBootStarter展示web项目api接口

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

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

粉丝 226
博文 82
码字总数 72407
作品 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注解,按道理应该不会这样,那应该是在浏览器访问界面的时候出的问题
在 spring-boot 中使用 swagger--SwaggerSpringBootStarter

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

阿信sxq
2017/07/21
342
0
使用swagger实现web api在线接口文档

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

杰克.陈
2017/12/20
0
0
C#开发微信门户及应用(47) - 整合Web API、微信后台管理及前端微信小程序的应用方案

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

walb呀
2017/12/04
0
0
HTTP 服务器中间件--Restc

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

lujjjh
2016/11/24
8.5K
9
使用 Aries 构建 OSGi 应用程序

Aries 旨在提供一个 OSGi 可插入框架来构建应用程序。本文将介绍一些 Aries 和 OSGi 概念,并展示如何创建可用于构建应用程序的 OSGi 兼容模块。 Apache Aries 的目标是支持企业应用程序的创...

IBMdW
2011/06/28
860
0

没有更多内容

加载失败,请刷新页面

加载更多

Pycharm上Django的使用 Day8

1.添加新条目 1>编写用于添加新条目的表单 在forms.py中创建一个与模型Entry相关联的表单 1处给字段'text'指定一个空标签 2处定义小部件widgets,widgets是一个HTML表单元素 2>定义new_entry...

不会TC的猫
15分钟前
2
0
MongoDB副本集

MongoDB介绍 早期版本使用master-slave,一主一从和MySQL类似,但slave在此架构中为只读,当主库宕机后,从库不能自动切换为主 目前已经淘汰master-slave模式,改为副本集,这种模式下有一个...

chencheng-linux
28分钟前
1
0
WebService 客户端记录

https://blog.csdn.net/qiuhan/article/details/49487009

呼呼南风
28分钟前
0
0
七牛云彭垚:智能平台的创新和发展

2018 年 11 月 14 日至 11 月 18 日,第二十届中国国际高新技术成果交易会(简称高交会)在深圳成功举办,七牛云作为国内领先的以数据智能和视觉智能为核心的企业级云计算服务商受邀参展。 ...

七牛云
35分钟前
0
0
Java内存模型原理,你真的理解透彻了吗?

内存模型产生背景 在介绍 Java 内存模型之前,我们先了解一下物理计算机中的并发问题,理解这些问题可以搞清楚内存模型产生的背景。 物理机遇到的并发问题与虚拟机中的情况有不少相似之处,物...

小刀爱编程
40分钟前
2
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部