一、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

三、常见用法和说明

  1. @Api:用在类上,说明该类的作用。
  2. @ApiOperation:注解来给API增加方法说明。
  3. @ApiImplicitParams : 用在方法上包含一组参数说明。
  4. @ApiImplicitParam:用来注解来给方法入参增加说明。
  5. @ApiResponses:用于表示一组响应
  6. @ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)

    l   @ApiModelProperty:描述一个model的属性

  7. @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的更多相关文章

  1. SpringBoot系列之i18n集成教程

    目录 1.环境搭建 2.resource bundle资源配置 3.LocaleResolver类 4.I18n配置类 5.Thymeleaf集成 SpringBoot系统之i18n国际化语言集成教程 ...

  2. Springboot系列:Springboot与Thymeleaf模板引擎整合基础教程(附源码)

    前言 由于在开发My Blog项目时使用了大量的技术整合,针对于部分框架的使用和整合的流程没有做详细的介绍和记录,导致有些朋友用起来有些吃力,因此打算在接下来的时间里做一些基础整合的介绍,当然,可能也 ...

  3. SPRING-BOOT系列之SpringBoot快速入门

    今天 , 正式来介绍SpringBoot快速入门 : 可以去如类似 https://docs.spring.io/spring-boot/docs/2.1.0.BUILD-SNAPSHOT/refer ...

  4. SPRING-BOOT系列之SpringBoot的诞生及其和微服务的关系

    转载自 : https://www.cnblogs.com/ityouknow/p/9034377.html 微服务架构 微服务的诞生并非偶然,它是在互联网高速发展,技术日新月异的变化以及传统架构无法 ...

  5. Springboot系列(七) 集成接口文档swagger,使用,测试

    Springboot 配置接口文档swagger 往期推荐 SpringBoot系列(一)idea新建Springboot项目 SpringBoot系列(二)入门知识 springBoot系列(三)配 ...

  6. SpringBoot系列(十四)集成邮件发送服务及邮件发送的几种方式

    往期推荐 SpringBoot系列(一)idea新建Springboot项目 SpringBoot系列(二)入门知识 springBoot系列(三)配置文件详解 SpringBoot系列(四)web静 ...

  7. Springboot 系列(十二)使用 Mybatis 集成 pagehelper 分页插件和 mapper 插件

    前言 在 Springboot 系列文章第十一篇里(使用 Mybatis(自动生成插件) 访问数据库),实验了 Springboot 结合 Mybatis 以及 Mybatis-generator 生 ...

  8. SpringBoot系列之集成Thymeleaf用法手册

    目录 1.模板引擎 2.Thymeleaf简介 2.1).Thymeleaf定义 2.2).适用模板 3.重要知识点 3.1).th:text和th:utext 3.2).标准表达式 3.3).Thy ...

  9. SpringBoot系列之集成jsp模板引擎

    目录 1.模板引擎简介 2.环境准备 4.源码原理简介 SpringBoot系列之集成jsp模板引擎 @ 1.模板引擎简介 引用百度百科的模板引擎解释: 模板引擎(这里特指用于Web开发的模板引擎)是 ...

随机推荐

  1. wildfly jobss 同时连接多个数据源 datasource xa-datasource

    由于需要从一个远程机器取数据.处理后保存到本地数据库处理.用 wildfly datasource 会报: [com.arjuna.ats.arjuna] (default task-6) ARJUN ...

  2. (转)在Eclipse中创建Maven多模块工程

    背景:以前只总结了怎么在命令行下创建maven的多模块项目,在eclipse下怎么创建不是很清楚.最近需要在git的资源库中上传多模块项目,方便后期的维护,所以将网上的资料进行整理. 原文链接:htt ...

  3. Codeforces Round #516 (Div. 2, by Moscow Team Olympiad) D. Labyrinth

    http://codeforces.com/contest/1064/problem/D 向上/向下加0,向左/右加1, step = 0,1,…… 求的是最少的步数,所以使用bfs. step=k ...

  4. codeblocks 输入、输出文件的位置

    codeblocks已经自动地规定了文件位置 另外:有些数据(数据量大)直接复制到exe中执行,会神奇地发生错误,估计是限制了一次粘贴到控制台的数据量.

  5. 第二节,TensorFlow 使用前馈神经网络实现手写数字识别

    一 感知器 感知器学习笔记:https://blog.csdn.net/liyuanbhu/article/details/51622695 感知器(Perceptron)是二分类的线性分类模型,其输 ...

  6. ActiveMQ集群简单测试+eclipse Zookeeper 插件 + 负载均衡

    ActiveMQ集群搭建好之后,接下来就该测试一下了. 一.先安装Zookeeper 的eclipse插件吧. 1. 打开 eclipse, Help -> Install New Softwa ...

  7. centOS7环境下安装jdk1.8

    首先下载jdk1.8  去官网下载jdk:http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151. ...

  8. JS文本框获取焦点

    所谓焦点,就是鼠标移上文本框的时候那个一闪一闪的光标.

  9. JAVA记录-POST与GET方式区别

    1.get是从服务器上获取数据的一种请求,post是向服务器提交数据的一种请求. 2.get是把参数数据队列加到提交表单的ACTION属性所指的URL中,值和表单内各个字段一一对应,在URL中可以看到 ...

  10. 多线程ExecutorService中submit和execute区别

    submit和execute都是 ExecutorService 的方法,都是添加线程到线程池中. 区别 三个区别: 1.接收的参数不一样 2.submit有返回值,而execute没有 Method ...