Swagger文档详解

1、Swagger介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(http
s://swagger.io/)。它的主要作用是：

使得前后端分离开发更加方便，有利于团队协作

接口的文档在线自动生成，降低后端开发人员编写接口文档的负担

功能测试 Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入Springfox ，即可非常简单快捷的使用Swagger

2、SpringBoot集成Swagger

引入依赖

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version>
</dependency>
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version>
</dependency>

我们一般在公共的工程中进行配置即可，因为其他微服务工程都直接或间接依赖

2.修改配置文件

   # 开启swagger swagger.enable=true

3.在对应工程的config包中添加一个配置类

@Configuration
// 和配置文件application.propertis中的配置对应
// havingValue 的值如果和配置文件的值相等，就开启swagger
@ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")
@EnableSwagger2  //开启swagger注解支持
public class SwaggerConfiguration {@Beanpublic Docket buildDocket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(buildApiInfo()).select()// 要扫描的API(Controller)基础包.apis(RequestHandlerSelectors.basePackage("cn.ittest.xxx")).paths(PathSelectors.any()).build();}private ApiInfo buildApiInfo() {Contact contact = new Contact("程序员","","");return new ApiInfoBuilder().title("开发平台-用户服务API文档").description("包含用户服务api").contact(contact).version("1.0.0").build();}
}

3、Swagger常用注解

在Java类中添加Swagger的注解即可生成Swagger接口文档，常用Swagger注解如下：

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数的描述信息
@ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数的描述信息

@ApiImplicitParam属性：

我们在ConsumerController中添加Swagger注解，代码如下所示：

@RestController
@Api(value = "测试服务的Controller", tags = "Consumer", description = "测试服务API")
public class ConsumerController {@ApiOperation("测试是否爱你")@PostMapping(path = "/love")@ApiImplicitParam(name = "name", value = "姓名", required = true, dataType = "String")public String hi(String name) {return "我 love " + name;}
}

启动后访问： http://localhost:端口号/服务名/swagger-ui.html
效果如下：

Swagger生成API文档的工作原理：
1、当服务启动时会扫描到SwaggerConfiguration类
2、在此类中指定了扫描包路径cn.ittext.，会找到在此包下及子包下标记有@RestController注解的controller类
3、根据controller类中的Swagger注解生成API文档

Swagger文档详解相关推荐

英集芯ip6809规格书pdf芯片文档详解及典型电路原理图
英集芯ip6809芯片是一款无线充电发送端控制器SOC芯片,兼容WPC Qi v1.2.4新标准.支持2-3线圈无线充电发射端应用,支持A28线圈.MP-A8线圈,支持客户线圈定制方案,支持5W.苹果 ...
jsoup解析和遍历一个html文档详解
解析和遍历一个HTML文档如何解析一个HTML文档: String html = "<html><head><title>First parse< ...
在MyEclipse中使用javadoc导出API文档详解
本篇文档介绍如何在MyEclipse中导出javadoc(API)帮助文档,并且使用htmlhelp.exe和jd2chm.exe生成chm文档. 具体步骤如下: 打开MyEclipse,选中想要制作 ...
【PDF】java使用Itext生成pdf文档--详解
[API接口] 一.Itext简介 API地址:javadoc/index.html:如 D:/MyJAR/原JAR包/PDF/itext-5.5.3/itextpdf-5.5.3-javadoc/i ...
BH1750 光照传感器文档详解及驱动设计
前言最近接触到一个应用,需要在低功耗的产品上加上光照度采集,正好最近有接触到一款光照传感器 BH1750 ,性能价格都合适,那么今天就抽空来好好测试一下. 那么要写一篇测试文章,我会尽量以新手的角度 ...
webservice的WSDL文档详解
WSDL – WebService Description Language – Web服务描述语言. –通过XML形式说明服务在什么地方-地址 –通过XML形式说明服务提供什么样的方法 – 如何调用 ...
Dubbo2.7文档详解
本篇博文参考dubbo官方文档本编博文参考javaguide之rpc 文章目录一.RPC 1.1 什么是 RPC? 1.2 为什么要用 RPC? 1.3 RPC 能帮助我们做什么呢? 1.4 RP ...
第5节：开发微信小程序之文档详解
前言前面4节,我们讲解了为什么要开这一个专栏,以及第一个小程序Hello World,与其说第一个小程序,不如说微信开发者工具为我们创建了一个基础工程项目!然后,又开发了一个真正实现突破0的小程序- ...
网络抓包工具翻译帮助文档详解教程
How To Set Up a Capture 1. 确保你做的事是被允许的! (1)意思是在不违反法律的情况下抓取可以被允许抓取的包. 2.一般设置 (1)权限的设置,你是否有权限去获取用户或者管理 ...

Swagger文档详解

1、Swagger介绍

2、SpringBoot集成Swagger

3、Swagger常用注解

Swagger文档详解相关推荐

最新文章

热门文章