springboot系列十三、springboot集成swaggerUI
一、Swagger介绍
Swagger能成为最受欢迎的REST APIs文档生成工具之一,有以下几个原因:
- Swagger 可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API。
- Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
- Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
- Swagger 有一个强大的社区,里面有许多强悍的贡献者。
Swagger 文档提供了一个方法,使我们可以用指定的 JSON 或者 YAML 摘要来描述你的 API,包括了比如 names、order 等 API 信息。
你可以通过一个文本编辑器来编辑 Swagger 文件,或者你也可以从你的代码注释中自动生成。各种工具都可以使用 Swagger 文件来生成互动的 API 文档。
二、配置及使用Swagger
1、引入依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2、添加配置类:SwaggerConfig.java
package com.example.demo.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2; /**
* Swagger2配置类
* 在与spring boot集成时,放在与Application.java同级的目录下。
* 通过@Configuration注解,让Spring来加载该类配置。
* 再通过@EnableSwagger2注解来启用Swagger2。
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig { /**
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
* 本例采用指定扫描的包路径来定义指定要建立API的目录。
*
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo"))
.paths(PathSelectors.any())
.build();
} /**
* 创建该API的基本信息(这些基本信息会展现在文档页面中)
* 访问地址:http://项目实际地址/swagger-ui.html
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("更多请关注:博客园小人物的奋斗")
.termsOfServiceUrl("http://www.cnblogs.com/wangzhuxing")
.contact("xing")
.version("1.0")
.build();
}
}
3、使用示例
1、注解Controller类
@Controller
@RequestMapping("/User")
@Api(description = "测试swagger注解的demo")
public class HelloWorldController {
@ResponseBody
@RequestMapping(value = "/getAllUser" ,method = RequestMethod.POST)
@ApiOperation(value = "获取用户信息",notes = "返回单个用户信息")
public List<UserPO> getAllUser(@ApiParam(required = false) @RequestBody User user) {
userService.addUser();
return userService.findAll();
}
}
2、注解入参和出参
package com.example.demo.bean;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable; public class User implements Serializable {
@ApiModelProperty(value = "用户id" ,example = "11")
private Long uid;
@ApiModelProperty(value = "用户姓名",example = "小明")
private String name;
@ApiModelProperty(value = "用户年龄",example = "25")
private Integer age;
public Long getUid() {
return uid;
}
public void setUid(Long uid) {
this.uid = uid;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
}
4、验证效果
访问:http://192.168.1.100:8080/swagger-ui.html
三、常见用法和说明
- @Api:用在类上,说明该类的作用。
- @ApiOperation:注解来给API增加方法说明。
- @ApiImplicitParams : 用在方法上包含一组参数说明。
- @ApiImplicitParam:用来注解来给方法入参增加说明。
- @ApiResponses:用于表示一组响应
@ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
l @ApiModelProperty:描述一个model的属性
- @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
l code:数字,例如400
l message:信息,例如"请求参数没填好"
l response:抛出异常的类
Swagger是一组开源项目,其中主要要项目如下:
1. Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
2. Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。
3. Swagger-js: 用于JavaScript的Swagger实现。
4. Swagger-node-express: Swagger模块,用于node.js的Express web应用框架。
5. Swagger-ui:一个无依赖的HTML、JS和CSS集合,可以为Swagger兼容API动态生成优雅文档。
6. Swagger-codegen:一个模板驱动引擎,通过分析用户Swagger资源声明以各种语言生成客户端代码。
springboot系列十三、springboot集成swaggerUI的更多相关文章
- SpringBoot系列之i18n集成教程
目录 1.环境搭建 2.resource bundle资源配置 3.LocaleResolver类 4.I18n配置类 5.Thymeleaf集成 SpringBoot系统之i18n国际化语言集成教程 ...
- Springboot系列:Springboot与Thymeleaf模板引擎整合基础教程(附源码)
前言 由于在开发My Blog项目时使用了大量的技术整合,针对于部分框架的使用和整合的流程没有做详细的介绍和记录,导致有些朋友用起来有些吃力,因此打算在接下来的时间里做一些基础整合的介绍,当然,可能也 ...
- SPRING-BOOT系列之SpringBoot快速入门
今天 , 正式来介绍SpringBoot快速入门 : 可以去如类似 https://docs.spring.io/spring-boot/docs/2.1.0.BUILD-SNAPSHOT/refer ...
- SPRING-BOOT系列之SpringBoot的诞生及其和微服务的关系
转载自 : https://www.cnblogs.com/ityouknow/p/9034377.html 微服务架构 微服务的诞生并非偶然,它是在互联网高速发展,技术日新月异的变化以及传统架构无法 ...
- Springboot系列(七) 集成接口文档swagger,使用,测试
Springboot 配置接口文档swagger 往期推荐 SpringBoot系列(一)idea新建Springboot项目 SpringBoot系列(二)入门知识 springBoot系列(三)配 ...
- SpringBoot系列(十四)集成邮件发送服务及邮件发送的几种方式
往期推荐 SpringBoot系列(一)idea新建Springboot项目 SpringBoot系列(二)入门知识 springBoot系列(三)配置文件详解 SpringBoot系列(四)web静 ...
- Springboot 系列(十二)使用 Mybatis 集成 pagehelper 分页插件和 mapper 插件
前言 在 Springboot 系列文章第十一篇里(使用 Mybatis(自动生成插件) 访问数据库),实验了 Springboot 结合 Mybatis 以及 Mybatis-generator 生 ...
- SpringBoot系列之集成Thymeleaf用法手册
目录 1.模板引擎 2.Thymeleaf简介 2.1).Thymeleaf定义 2.2).适用模板 3.重要知识点 3.1).th:text和th:utext 3.2).标准表达式 3.3).Thy ...
- SpringBoot系列之集成jsp模板引擎
目录 1.模板引擎简介 2.环境准备 4.源码原理简介 SpringBoot系列之集成jsp模板引擎 @ 1.模板引擎简介 引用百度百科的模板引擎解释: 模板引擎(这里特指用于Web开发的模板引擎)是 ...
随机推荐
- 神奇的操作——线段树合并(例题: BZOJ2212)
什么是线段树合并? 首先你需要动态开点的线段树.(对每个节点维护左儿子.右儿子.存储的数据,然后要修改某儿子所在的区间中的数据的时候再创建该节点.) 考虑这样一个问题: 你现在有两棵权值线段树(大概是 ...
- 洛谷 P2059 [JLOI2013]卡牌游戏 解题报告
P2059 [JLOI2013]卡牌游戏 题意 有\(n\)个人玩约瑟夫游戏,有\(m\)张卡,每张卡上有一个正整数,每次庄家有放回的抽一张卡,干掉从庄家起顺时针的第\(k\)个人(计算庄家),干掉的 ...
- 字符串格式化(七)-format
print("i am %s" %'admin') # i am admin msg = "i am %s" %'Alex' print(msg) # i am ...
- 牛客练习赛29 F 算式子
https://www.nowcoder.com/acm/contest/211/F 经典题. 1.分区间 2.向下取整的值变化 & 合并相同值 #include <bits/stdc+ ...
- Ubuntu下安装nfs服务器
安装 NFS 软件包在 ubuntu 终端输入下面命令安装 NFS 服务器:vmuser@Linux-host: ~$ sudo apt-get install nfs-kernel-server # ...
- mockery expectation 覆盖
public function testOverrideExpectation() { // 如果没有指定 expectation 调用次数, 那么每次调用 mock 的 expectation 方法 ...
- mac idea merge后需要手动push到远程服务器
- Django 日志配置按日期滚动
记录下Django关于日期的配置,以及如何根据日期滚动切割日志的问题. 配置的源码在githun上 https://github.com/blackmatrix7/django-examples/tr ...
- Linux集群部署自定义时间同步服务器(ntpd)
Linux集群部署自定义时间同步服务器(ntpd) 作者:尹正杰 版权声明:原创作品,谢绝转载!否则将追究法律责任. 身为一名运维人员,在搭建集群的时候,第一步需要做的就是同步每个机器的时间,尤其是在 ...
- Python字符编码以及循环机制介绍
Python字符编码以及循环机制介绍 作者:尹正杰 版权声明:原创作品,谢绝转载!否则将追究法律责任. 身为一名运维人员就得不断的学习,那么如何身为运维的你是否已经嗅探已经很火的Python编程啦?大 ...