Spring整合swagger
2024-04-15 00:39:25
最近主要负责接口开发，每次都用以前用过的postman，发现配置参数这些比较麻烦，然后有人推荐用swagger。于是尝试将swagger整合到项目中。
配置
//pomx.xml 添加依赖
<dependencies><dependency><groupId>junit</groupId><artifactId>junit</artifactId><version>4.12</version></dependency><dependency><groupId>org.slf4j</groupId><artifactId>slf4j-log4j12</artifactId><version>1.7.7</version></dependency><dependency><groupId>javax.servlet</groupId><artifactId>javax.servlet-api</artifactId><version>3.0.1</version><scope>provided</scope></dependency><dependency><groupId>org.springframework</groupId><artifactId>spring-context</artifactId><version>4.3.7.RELEASE</version></dependency><dependency><groupId>org.springframework</groupId><artifactId>spring-context-support</artifactId><version>4.3.7.RELEASE</version></dependency><dependency><groupId>org.springframework</groupId><artifactId>spring-web</artifactId><version>4.3.7.RELEASE</version></dependency><dependency><groupId>org.springframework</groupId><artifactId>spring-webmvc</artifactId><version>4.3.7.RELEASE</version></dependency><dependency><groupId>org.springframework</groupId><artifactId>spring-tx</artifactId><version>4.3.7.RELEASE</version></dependency><dependency><groupId>commons-lang</groupId><artifactId>commons-lang</artifactId><version>2.6</version></dependency><dependency><groupId>commons-codec</groupId><artifactId>commons-codec</artifactId><version>1.10</version></dependency><dependency><groupId>commons-httpclient</groupId><artifactId>commons-httpclient</artifactId><version>3.1</version></dependency><dependency><groupId>org.springframework</groupId><artifactId>spring-test</artifactId><version>4.3.7.RELEASE</version></dependency><!-- apache httpclient --><dependency><groupId>org.apache.httpcomponents</groupId><artifactId>httpclient</artifactId><version>4.5.2</version></dependency><!-- apache commons io --><dependency><groupId>commons-io</groupId><artifactId>commons-io</artifactId><version>2.4</version></dependency><!-- fastjson --><dependency><groupId>com.alibaba</groupId><artifactId>fastjson</artifactId><version>1.2.32</version></dependency><!-- jstl --><dependency><groupId>javax.servlet</groupId><artifactId>jstl</artifactId><version>1.2</version><type>jar</type></dependency><dependency><groupId>javax.servlet.jsp</groupId><artifactId>javax.servlet.jsp-api</artifactId><version>2.3.1</version><scope>provided</scope></dependency><!-- swagger --><dependency><groupId>com.mangofactory</groupId><artifactId>swagger-springmvc</artifactId><version>1.0.2</version></dependency><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.6.1</version></dependency><dependency><groupId>com.fasterxml.jackson.core</groupId><artifactId>jackson-annotations</artifactId><version>2.8.9</version></dependency><dependency><groupId>com.fasterxml.jackson.core</groupId><artifactId>jackson-databind</artifactId><version>2.8.9</version></dependency><dependency><groupId>com.fasterxml.jackson.core</groupId><artifactId>jackson-core</artifactId><version>2.8.9</version></dependency><dependency><groupId>com.google.guava</groupId><artifactId>guava</artifactId><version>22.0</version></dependency></dependencies>
如果项目中想要使用注解@ApiImplicitParam。则一定要配置com.google.guava.不然后会抛出异常。
//springmvc spring-servlet.xml配置
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:mvc="http://www.springframework.org/schema/mvc" xmlns:context="http://www.springframework.org/schema/context"xmlns:tx="http://www.springframework.org/schema/tx" xmlns:aop="http://www.springframework.org/schema/aop"xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.1.xsdhttp://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.1.xsdhttp://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc-3.1.xsdhttp://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.5.xsd"><!-- 启用spring mvc 注解 --><context:annotation-config /><!-- 设置使用注解的类所在的jar包 --><context:component-scan base-package="com.ezparking"><context:include-filter type="annotation" expression="org.springframework.stereotype.Controller"/></context:component-scan><bean class="org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter"/><bean id="viewResolver" class="org.springframework.web.servlet.view.InternalResourceViewResolver"><property name="viewClass" value="org.springframework.web.servlet.view.JstlView"></property><property name="prefix" value="/WEB-INF/views/"></property><property name="suffix" value=".jsp"></property></bean><mvc:annotation-driven><mvc:message-converters register-defaults="true"><bean class="org.springframework.http.converter.StringHttpMessageConverter"><constructor-arg value="UTF-8" /></bean></mvc:message-converters></mvc:annotation-driven><mvc:resources location="/static/" mapping="/static/**"/><!--配置静态资源访问 --><mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/> <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>
</beans>//spring applicationContext.xml
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:mvc="http://www.springframework.org/schema/mvc"xmlns:context="http://www.springframework.org/schema/context" xmlns:aop="http://www.springframework.org/schema/aop" xmlns:tx="http://www.springframework.org/schema/tx"xmlns:jpa="http://www.springframework.org/schema/data/jpa" xmlns:task="http://www.springframework.org/schema/task"xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.0.xsdhttp://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc-4.0.xsdhttp://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-4.0.xsdhttp://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-4.0.xsdhttp://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-4.0.xsdhttp://www.springframework.org/schema/data/jpa http://www.springframework.org/schema/data/jpa/spring-jpa-1.3.xsdhttp://www.springframework.org/schema/task http://www.springframework.org/schema/task/spring-task-4.0.xsd"><!-- 引入注解扫描器 --><context:annotation-config /><!-- 配置要扫描的包 --><context:component-scan base-package="com.ezparking" ><context:exclude-filter type="annotation" expression="org.springframework.stereotype.Controller"/></context:component-scan><mvc:annotation-driven />
</beans>
这里配置也是最简单配置。本项目主要在于整合swagger.
//在代码中引入swagger配置类。这个配置类就等于构建了一个MVC的接口容器Docket。这个容器可以配置管理哪些接口import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@EnableSwagger2
@EnableWebMvc
@Configuration
public class ApplicationSwaggerConfig extends WebMvcConfigurationSupport {public Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() /*注册回调*/.apis(RequestHandlerSelectors.basePackage("com.ezparking.controller"))/*配置API的基本包路径。一般接口都配置在controller包里。当然可以根据自己要求配置*/.paths(PathSelectors.any())/*接口的路径配置。any就是可以是任意路径*/.build();}/*接口文档的一些基本信息可以自己根据具体配置*/private ApiInfo apiInfo() {return new ApiInfoBuilder().title("restulful API").termsOfServiceUrl("www.baidu.com").contact(new Contact("ezparking", "", "")).version("1.0.0").build();}}@Controller
@RequestMapping("/")
@Api(description="大数据接口")
public class DashboardController {/*** RTPI数据统计*paramType path 用于restfule rtpi/{id}/{age} query 参数添加在url后面*consumes="application/x-www-form-urlencoded" 配置请求在数跟在url后面保证可以映射到对应的参数* @return RTPI数据统计信息*/@RequestMapping(value="/rtpi",produces = "application/json; charset=utf-8")@ResponseBody@ApiOperation(value="获取数据", httpMethod="POST",consumes="application/x-www-form-urlencoded", notes="根据停车场获取数据")@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "用户姓名", required = false, dataType = "String",paramType="query"),@ApiImplicitParam(name = "age", value = "用户年龄", required = false, dataType = "String",paramType="query"),@ApiImplicitParam(name = "parking", value = "停车场", required = false, dataType = "Parking")})public String rtpiData( String id, String age,Parking parking) {System.out.println(id + age+parking.getAddress()+parking.getName());return HttpUtils.doGet(propertiesUtils.getProperty("rtpi"));}}
在一个controller中添加API的注解。然后部署项目。启动。访问路径http://localhost:8080/rtpi-dashboard/swagger-ui.html
得到如下页面
点击任意接口
到这里基本整合完毕。下面是一些常用的注解参数的文档整理。
- Api
类注解。
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface Api {//url路径值String value() default "";//如果设置这个值、value的值会被覆盖String[] tags() default "";//接口的描述。已过时。但是我没发现用什么注解来代替。@Deprecated String description() default "";//如果有多个接口类集合，可以决定该接口类的位置@Deprecated int position() default 0;//"application/json, application/xml" 指定返回的内容类型String produces() default "";//"application/json, application/xml" 指定处理的请求类型String consumes() default "";//支持哪些协议。如：http, https, ws, wss多个协议用逗号分隔String protocols() default "";//权限配置Authorization[] authorizations() default @Authorization(value = "");//是否隐藏。boolean hidden() default false;
}- ApiOperation
方法注解。
//描述方法用途String value();//详细描述String notes() default "";//如果配置将会覆盖valueString[] tags() default "";//返回的对象Class<?> response() default Void.class;//返回可以包含的集合 "List", "Set" or "Map". 其它都会被忽略String responseContainer() default "";//返回的对象引用。注解次值将会覆盖responseString responseReference() default "";//接口方法类型。"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH".String httpMethod() default "";//接口的位置@Deprecated int position() default 0;//别名？不知道有啥用目前String nickname() default "";//响应的类型 "application/json, application/xml"String produces() default "";//请求的类型。"application/json, application/xml"String consumes() default "";//协议String protocols() default "";//权限配置Authorization[] authorizations() default @Authorization(value = "");//是否隐藏boolean hidden() default false;//响应头ResponseHeader[] responseHeaders() default @ResponseHeader(name = "", response = Void.class);//响应编码int code() default 200;//扩展Extension[] extensions() default @Extension(properties = @ExtensionProperty(name = "", value = ""));- ApiImplicitParams
一个ApiImplicitParams 包含多个 ApiImplicitParam 如：
@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "用户姓名", required = false, dataType = "String",paramType="path"),@ApiImplicitParam(name = "age", value = "用户年龄", required = false, dataType = "String",paramType="path"),@ApiImplicitParam(name = "parking", value = "停车场", required = false, dataType = "Parking")- ApiImplicitParam
方法注解
//参数名称String name() default "";//默认值String defaultValue() default "";//设置参数范围 String allowableValues() default "";//是否必须boolean required() default false;//过滤某个参数String access() default "";//允许某个参数多个值boolean allowMultiple() default false;//参数类型String dataType() default "";//参数类型。配置这个会覆盖dataTypeClass<?> dataTypeClass() default Void.class;//参数路径类型。path，query,body,header,form.这个参数比较重要。如果path，说明该参数应该是restful风格。对应的参数应该用@PathVariable修饰。 如果参数是其它类型，那么在@ApiOperation 中应该指定consumes="application/x-www-form-urlencoded"。否则默认的是json格式将无法映射到具体的参数。String paramType() default "";String example() default "";Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = ""));String type() default "";String format() default "";//允许为空boolean allowEmptyValue() default false;//只读boolean readOnly() default false;String collectionFormat() default "";没写注释的说明目前还没用到，也还没真正弄明白啥意思。希望随着用的熟悉能越来越多的理解更多的参数。了解上面的参数基本已经能够配置常用的接口管理。
Spring整合swagger相关推荐
- Spring Boot 整合 Swagger
一.为什么要用 Swagger 现在的开发模式,一般都是前后端分离的,开发接口文档就显得尤为重要,前端人员需要按照后端的功能文档调用对应的接口.在没有使用 API 文档之前,很多公司都是在纸或者 Ma ...
- Spring Boot 整合Swagger实现API管理
Spring Boot 整合Swagger实现API管理 1 Swagger介绍 根据官网的介绍: https://swagger.io Swagger 是一款RESTFUL接口的.基于YAML.JS ...
- 六、springboot整合swagger
六.springboot整合swagger 简介 swagger 提供最强大,最易用的工具,以充分利用OpenAPI规范. 官网 : https://swagger.io/ 准备工作 pom.xml ...
- 解决高版本SpringBoot整合swagger时启动报错：Failed to start bean ‘documentationPluginsBootstrapper‘ 问题
一.控制台的报错信息 2021-12-29 15:15:04 [main] ERROR org.springframework.boot.SpringApplication - Application ...
- 实体类 接口_spring-boot-route（五）整合Swagger生成接口文档
目前,大多数公司都采用了前后端分离的开发模式,为了解决前后端人员的沟通问题,后端人员在开发接口的时候会选择使用swagger2来生成对应的接口文档,swagger2提供了强大的页面调试功能,这样可以有 ...
- gin ip 和 本地访问的结果不一样_golang web开发——gin实战之整合swagger
背景 如果我们之前搞过java web开发,我们应该都知道swagger这个API文档自动生成利器,有了swagger可以方便我们与客户端的联调,基本上是一目了然,swagger支持java,自然它也 ...
- SpringBoot基础学习之整合Swagger框架(上篇)
前言: 小伙伴们,大家好,我是狂奔の蜗牛rz,当然你们可以叫我蜗牛君,我是一个学习Java半年多时间的小菜鸟,同时还有一个伟大的梦想,那就是有朝一日,成为一个优秀的Java架构师. 这个SpringB ...
- SpringBoot一站式功能提供框架（一）整合MybatisPlus、整合Swagger Knif4j、整合Druid多数据源--柚子真好吃
SpringBoot一站式功能提供框架(一)整合MybatisPlus.整合Swagger Knif4j.整合Druid多数据源--柚子真好吃 一.前言 二.功能描述 三.具体实现 四.开源地址 一. ...
- SSM整合Swagger
现在后端比较流行的框架是spring boot.使用spring boot集成swagger也非常方便.这里我们先来看看ssm整合Swagger. 导入依赖 spring和swagger之间存在版本问 ...
最新文章
- python跟java-python(一)：python与java语法的异同之处
- tcp udp区别优缺点_Linux网络编程面试题--tcp和udp的区别
- [转]Vim常用命令速查
- css案例学习之span边框实现的特殊效果
- Python培训的基础知识
- java hashcode 例子_Java UUID hashCode()用法及代码示例
- 基于yolo5工地安全帽和禁入危险区域识别系统,附数据集
- 启用计算机浏览器摄像头,如何启用浏览器进行摄像头访问？
- 【AlphaGo之后会是什么】一文读懂人工智能打德扑
- 处女座的砝码 long double
- 妙控鼠标灵敏度太低怎么办
- Mybatis简介及其核心概念
- PCIE：如何获取PCIE学习资料文档
- 在使用集合中的contains(),要根据实际情况改写集合中对象的equals(Object obj）方法------改写List集合中equals(Object obj)的方法
- android之按钮添加声音
- 质谱和蛋白质组学领域简述
- 指纹识别属于计算机技术,指纹识别技术主要涉及四个功能，是哪四个呢？
- 论文：lda2vev:Mixing Dirichlet Topic Models and Word Embeddings to Make lda2vec
- 关于“淘宝爆款”的数据抓取与数据分析
- 疫情期间，酒店用“场景+玩法”引流获客