文档章节

使用SwaggerSpringBootStarter展示web项目api接口

阿信sxq
 阿信sxq
发布于 2017/07/27 15:41
字数 1235
阅读 1426
收藏 61
点赞 0
评论 9

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

阿信sxq

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

评论(9)

阿信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注解,按道理应该不会这样,那应该是在浏览器访问界面的时候出的问题
阿信sxq
阿信sxq

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

在application.properties 中的中文,页面上是乱码 不知道哪里要做处理
在这个文件中只能存unicode的,中文需要转换,读取出来的才能是正常的,可以去看看Properties类的介绍哦
沉浮aim
沉浮aim
在application.properties 中的中文,页面上是乱码 不知道哪里要做处理
java9
java9
mark
weifusheng
weifusheng
mark
h
hao5ang
不错,一直在用
微信小程序结合后台数据管理实现商品数据的动态展示、维护

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

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
使用 Aries 构建 OSGi 应用程序

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

IBMdW
2011/06/28
860
0
C#开发微信门户及应用(43)--微信各个项目模块的定义和相互关系

我们在开发微信相关的应用的时候,一般需要完善的基础模块支持,包括微信公众号,微信企业号,以及一些业务模块的支持,一般随着功能的增多,我们需要非常清晰的界定他们的关系。模块的分拆以...

walb呀
2017/12/04
0
0
Springfox与SpringMvc集成实现接口文档化

准备环境 一个web服务器(我使用的是tomcat、当然nginx都可以) eclipse开发环境使用SpringMvc框架的源码(我使用springfox官网提供的demo) 下载swagger-ui源码 实现目的 eclipse中启动后台项目...

zzuqiang
2016/11/24
182
0
Web API应用架构在Winform混合框架中的应用(4)--利用代码生成工具快速开发整套应用

前面几篇介绍了Web API的基础信息,以及如何基于混合框架的方式在WInform界面里面整合了Web API的接入方式,虽然我们看似调用过程比较复杂,但是基于整个框架的支持和考虑,我们提供了代码生...

walb呀
2017/12/04
0
0
havebeen/itfarm

#itfarm 一个技术分享的内容网站,包括web端用于用户浏览操作,和后台文章管理 项目的结构如下: itfarm-admin itfarm-api itfarm-cache itfarm-commons itfarm-provider itfarm-service itf...

havebeen
2016/09/03
0
0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

用 Python 实现打飞机,让子弹飞吧!

所用技术和软件 python 2.7 pygame 1.9.3 pyCharm 准备工作 安装好 pygame 在第一次使用 pygame 的时候,pyCharm 会自动 install pygame。 下载好使用的素材。 技术实现 初始化 pygame 首先要...

猫咪编程
3分钟前
0
0
MySQL的行锁和表锁

简单总结一下行锁和表锁。 行锁 每次操作锁住一行数据。开销大,加锁慢;会出现死锁;锁定粒度最小,发生锁冲突的概率最低,并发度也最高。 表锁 每次操作锁住整张表。开销小,加锁快;不会出...

to_ln
5分钟前
0
0
Java IO类库之字节数组输入流ByteArrayInputStream

一、ByteArrayInputStream字节数组输入流介绍 ByteArrayInputStream是字节数组输入流,继承自InputStream。它的内部包含一个缓冲区,是一个字节数组,缓冲数组用于保存从流中读取的字节数据,...

老韭菜
7分钟前
0
0
iOS安全应该做哪些事情

1. 尽量使用HTTPS协议。 2. 密码提交的时候,密码使用SHA256加密后传输,MD5等经过哈希碰撞已经可以推算出原文。 3. 密码提交的时候,可以加盐。 4. 密码保存在本地的时候,尽量使用钥匙串保...

HOrange
13分钟前
0
0
react native 注意事项

1. 环境参考官网 android studio 必装 java jdk安装 1.8版本(环境建议自己一步一步配置,切记不要 apt ) 2.有改变编译内容发现 会白屏,然后APP消失,请卸载原来的测试 appinfo (连续两次...

304158
20分钟前
0
0
FOMO游戏代码解析

源代码在此处

怎当她临去时秋波那一转
25分钟前
1
0
EOS智能合约与DApp开发入门

EOS的是Block.One主导研发的一个区块链底层公链系统,它专门为支撑商业去中心化 应用(Decentralized Application)而设计,其代码开源。 比特币被称为区块链1.0,因为它开辟了数字加密货币的...

笔阁
37分钟前
1
0
编译cjson到dll

https://blog.csdn.net/mengzhisuoliu/article/details/52203724 编译完成后 是纯lua实现的json decode 的10倍以上...

梦想游戏人
47分钟前
0
0
JS基础- Date 对象

Date 对象 Date 对象用于处理日期和时间。 创建 Date 对象的语法: var myDate=new Date() 注释:Date 对象会自动把当前日期和时间保存为其初始值。 Date 对象属性 属性 描述 constructor 返...

ZHAO_JH
49分钟前
0
0
Python数据分析numpy(1)

Python开源的科学计算基础库 1.表示N维数组对象ndarray 2.线性代数、傅里叶变换、随机数生成 3.广播函数,整合c++、c 一.数据的维度 1.数据 2.数据维度 3.一维数据 (1)特点 (2)Python中的...

十年磨一剑3344
52分钟前
1
0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

返回顶部
顶部