swagger-ui集成

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

swagger简介

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTfu风格的web服务。目标是使客户端和文件系统作为服务器一同样的速度来更新文件的方法，参数和模型紧密集成到服务器。这个解释简单点来讲就是说，swagger是一款可以根据restful风格生成的接口开发文档，并且支持做测试的一款中间软件。

swagger-ui集成步骤

(在一个现有的springboot项目中集成测试的，不要在意包路径以及类的名称)

1、集成swagger相关依赖

<!-- swagger-api 依赖开始 -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.6.1</version>
</dependency>
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.6.1</version>
</dependency>
<!-- swagger-api 依赖结束 -->

引入相关jar包以后，可打开springfox-swagger-ui-2.6.1.jar下面的：\META-INF\resources\
可看到jar包中自带的swagger-ui.html，以及/webjars/下面html所引用到的相关前端渲染代码(css、js、fonts、images…)
搭建成功后的swagger页面就是这个html

2、配置swagger相关信息

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;/*** swagger相关配置** @auther SwaggerConfig* @create xxxx/xx/xx*/@Configuration // 标注此类是一个配置类
@ComponentScan(basePackages = {"com.redis.simple.redissimple.controller"}) // 扫描要加载的包路径
public class SwaggerConfig {@Beanpublic Docket customDocket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());}private ApiInfo apiInfo() {return new ApiInfo("title", // 文档标题"description", // 文档描述"version", // 文档版本"termsOfServiceUrl",new Contact("name","url","email"), // 作者信息"license","licenseUrl");}}

3、配置相关的访问映射

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;/*** 配置相关的访问映射** @auther SwaggerMvcConfig* @create xxxx/xx/xx*/@Configuration
public class SwaggerMvcConfig implements WebMvcConfigurer {@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {// 配置前端访问此路径，映射到 springfox-swagger-ui-2.6.1.jar下面的：\META-INF\resources\swagger-ui.htmlregistry.addResourceHandler("swagger-ui.html") .addResourceLocations("classpath:/META-INF/resources/");// 加载swagger-ui.html同级目录下webjars下相关的前端代码(css、js、fonts、images...)registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/");}
}

4、编写测试接口

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;/*** @auther SwaggerSimpleController* @create xxxx/xx/xx*/
@RestController
@Api(tags = {"swagger-ui-test"}) // 描述该类的作用
public class SwaggerSimpleController {@ApiOperation("swagger-ui 接口") // 描述方法的作用@ApiImplicitParams({ // 描述该接口的所有参数@ApiImplicitParam(name = "name",paramType = "query",value = "名称",required = true)})@GetMapping(value = "swaggerSimple")public String swaggerSimple(@RequestParam String name){return "hello : "+name;}}

5、启动类配置启用swagger并且启动项目

@SpringBootApplication
@EnableSwagger2 // 启用swagger-ui
public class RedisSimpleApplication {public static void main(String[] args) {SpringApplication.run(RedisSimpleApplication.class, args);}}

6、访问：http://localhost:8080/swagger-ui.html

swagger常用注解

@Api ：用在类上，说明该类的作用
@ApiOperation ：用在方法上，说明方法的作用
@ApiImplicitParams ：用在方法上包含一组参数说明
@ApiImplicitParam ：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面paramType：参数放在哪个地方header-->请求参数的获取：@RequestHeaderquery-->请求参数的获取：@RequestParampath（用于restful接口）-->请求参数的获取：@PathVariablebody（不常用）form（不常用）name：参数名dataType：参数类型required：参数是否必须传value：参数的意思defaultValue：参数的默认值
@ApiResponses ：用于表示一组响应
@ApiResponse ：用在@ApiResponses中，一般用于表达一个错误的响应信息code：数字，例如400message：信息，例如"请求参数没填好"response：抛出异常的类
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）@ApiModelProperty：描述一个model的属性response：抛出异常的类
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）@ApiModelProperty：描述一个model的属性

开发过程中swagger-ui快速集成详解相关推荐

Burp Suite中Intruder模块的使用详解
Burp Suite中Intruder模块的使用详解 Intruder(入侵者) Target(目标) Attack Target Positions(位置) Payload Positions Pa ...
ueditor上传组件显示乱码_最全面的移动端 UI组件设计详解：中篇
上一期给大家讲解了<最全面的移动端UI组件设计详解:上篇>,主要分享了:布局组件和导航组件2个部分:这次给大家带来:基础组件.表单组件和反馈组件详解,希望你在设计APP.小程序.H5页面中 ...
Android中measure过程、WRAP_CONTENT详解以及xml布局文件解析流程浅析(下)
本文原创, 转载请注明出处:http://blog.csdn.net/qinjuning 上篇文章<<Android中measure过程.WRAP_CONTENT详解以及xml布局文 ...
java web json_java web中对json的使用详解
一.在Java Web的开发过程中,如果希望调用Java对象转化成JSON对象等操作.则需要引入以下jar包,不然运行时则报错. 1.commons-beanutils.jar 2.commons-c ...
iOS中的HotFix方案总结详解
iOS中的HotFix方案总结详解相信HotFix大家应该都很熟悉了,今天主要对于最近调研的一些方案做一些总结.iOS中的HotFix方案大致可以分为四种: WaxPatch(Alibaba) Dy ...
python符号格式化设置区间_Python 数值区间处理_对interval 库的快速入门详解
使用 Python 进行数据处理的时候,常常会遇到判断一个数是否在一个区间内的操作.我们可以使用 if else 进行判断,但是,既然使用了 Python,那我们当然是想找一下有没有现成的轮子可以用. ...
java实现for文件删除_Java 添加、删除、替换、格式化Word中的文本的步骤详解（基于Spire.Cloud.SDK for Java）...
Spire.Cloud.SDK for Java提供了TextRangesApi接口可通过addTextRange()添加文本.deleteTextRange()删除文本.updateTextRang ...
eclipse配置python开发环境_Eclipse中配置python开发环境详解
Eclipse中配置python开发环境详解 1.下载python安装包.python-2.6.6.msi.并安装. 默认python会安装在C:\Python26下,查看环境变量,如果没有在path ...
C# ABP WebApi与Swagger UI的集成
C# ABP WebApi与Swagger UI的集成本文是配置WebApi与Swagger UI,可以参照 http://www.cnblogs.com/farb/p/ABPSwaggerUIIn ...

开发过程中swagger-ui快速集成详解

swagger-ui集成

swagger简介