关于springmvc4整合swagger2配置和jar依赖

最新推荐文章于 2024-05-17 17:13:24 发布

麦田的一米阳光

最新推荐文章于 2024-05-17 17:13:24 发布

阅读量2.5k

点赞数 2

分类专栏： Java语言文章标签： swagger springmvc API接口文档

本文链接：https://blog.csdn.net/pshaoyi/article/details/98745579

版权

Java语言专栏收录该内容

41 篇文章 0 订阅

订阅专栏

jar依赖

可从从 https://mvnrepository.com/ 网站进行下载或者mavne 导入

<dependency>
	<groupId>org.codehaus.jackson</groupId>
	<artifactId>jackson-mapper-asl</artifactId>
	<version>1.9.13</version>
</dependency>
<dependency>
	<groupId>org.codehaus.jackson</groupId>
	<artifactId>jackson-core-asl</artifactId>
	<version>1.9.13</version>
</dependency>
<dependency>
	 <groupId>com.fasterxml.jackson.core</groupId>
	 <artifactId>jackson-core</artifactId>
	 <version>2.9.2</version>
</dependency>
<dependency>
	 <groupId>com.fasterxml.jackson.core</groupId>
	 <artifactId>jackson-annotations</artifactId>
	 <version>2.9.2</version>
</dependency>
<dependency>
	 <groupId>com.fasterxml.jackson.core</groupId>
	 <artifactId>jackson-databind</artifactId>
	 <version>2.9.2</version>
</dependency>
<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>
<!-- google -->
<dependency>
	<groupId>com.google.guava</groupId>
	<artifactId>guava</artifactId>
	<version>22.0</version>
</dependency>

web.xml 配置

<servlet>
	<servlet-name>FrontMvc</servlet-name>
	<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
	<init-param>
		<param-name>contextConfigLocation</param-name>
		<param-value>/WEB-INF/config/spring-front-mvc.xml</param-value>
	</init-param>
	<load-on-startup>1</load-on-startup>
</servlet>


<servlet-mapping>
	<servlet-name>FrontMvc</servlet-name>
	<url-pattern>/</url-pattern>
</servlet-mapping>

spring-mvc.xml 配置

<!-- 扫描Controller -->
<context:component-scan base-package="com.swagger" />
	
<!-- 静态资源释放 -->
<mvc:resources mapping="/swagger/**" location="/swagger/"/>

SwaggerConfig配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import springfox.documentation.builders.ApiInfoBuilder;
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;
/**
 * @Configuration 声明该类为配置类
 * @EnableSwagger2 声明启动Swagger2
 * @EnableWebMvc 声明启动mvc 配置此注解通过包扫描，不需要进行spring bean xml 配置
 * */
@Configuration 
@EnableSwagger2 
@EnableWebMvc 
public class SwaggerConfig {
	
	@Bean
	public Docket api() {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
				.apis(RequestHandlerSelectors.basePackage("com.coupon.action"))// 扫描的包路径
				.build();
	}

	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("你的项目 API接口").description("此API提供接口调用").license("License Version 2.0")
				.version("2.0").build();
	}
}

controller配置


import java.util.List;

import javax.servlet.http.HttpServletRequest;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;

import com.bean.Person;
import com.service.PersonService;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;

@RestController
@RequestMapping("/person")
@Api(tags = "人员接口",description="人员文档说明",hidden=true)
public class PersonController {

	@Autowired
	private PersonService personService;
	
	@RequestMapping(value="/findAll")
	@ApiOperation(value="查询所有的人员",notes="查询所有的人员接口说明")
	@ApiImplicitParams({
		@ApiImplicitParam(name="month",value="年月，格式为：201801",dataType="String", paramType = "query"),
		@ApiImplicitParam(name="pageNo",value="页码",dataType="Integer", paramType = "query"),
		@ApiImplicitParam(name="pageSize",value="每页条数",dataType="Integer", paramType = "query"),
		@ApiImplicitParam(name="name",value="业务员名称",dataType="String", paramType = "query"),
		@ApiImplicitParam(name="orderType",value="排序类型",dataType="String", paramType = "query"),
	})
	@ApiResponse(response=Person.class, code = 200, message = "接口返回对象参数")
	@ResponseBody
	public List<Person> findAll(HttpServletRequest request,String month,Integer pageNo, Integer pageSize,String name,String orderType) {
		List<Person> list = personService.selectAll();
		return list;
	}
	
}

Swagger-UI配置

Swagger扫描解析得到的是一个json文档，对于用户不太友好。

下面介绍swagger-ui，它能够友好的展示解析得到的接口说明内容。

从https://github.com/swagger-api/swagger-ui 获取其所有的 dist 目录下东西放到需要集成的项目里，本文放入 src/main/webapp/swagger/ 目录下。

修改swagger目录下 index.html或者swagger-ui.html

默认是从连接http://petstore.swagger.io/v2/swagger.json 获取 API 的 JSON，这里需要将url值修改为http://{ip}:{port}/{projectName}/api-docs的形式，{}中的值根据自身情况填写。

比如我的url值为：http://localhost:8080/v2/api-docs

if (url && url.length > 1) {
url = decodeURIComponent(url[1]);
} else {
url = "http://localhost:8080/v2/api-docs";
}

因为swagger-ui项目都是静态资源，restful形式的拦截方法会将静态资源进行拦截处理，所以在springmvc配置文件中需要配置对静态文件的处理方式。

几款漂亮的Swagger UI 框架

https://gitee.com/caspar-chen/Swagger-UI-layer

https://gitee.com/xiaoym/swagger-bootstrap-ui

注解全参数

以下是swagger2注解中的全参数，有兴趣可以都试试

@Api

Api 标记可以标记一个Controller类做为swagger 文档资源，使用方式

属性名称	备注
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏

@ApiOperation每一个url资源的定义,使用方式

属性名称	备注
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏
response	返回的对象
responseContainer	这些对象是有效的 “List”, “Set” or “Map”.，其他无效
httpMethod	“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
code	http的状态码默认 200
extensions	扩展属性

@ApiParam标记

public ResponseEntity createUser(@RequestBody @ApiParam(value = “user”, required = true) User user)

属性名称	备注
name	属性名称
value	属性值
defaultValue	默认属性值
allowableValues	可以不配置
required	是否属性必填
access	不过多描述
allowMultiple	默认为false
hidden	隐藏该属性
example	举例子

@ApiImplicitParam对容器的描述

属性名称	备注
name	属性名称
value	属性值
defaultValue	默认值
allowableValues	可以不可配置
required	是否属性必填
access	不可过多描述
allowMutiple	默认为false
dataType	数据类型
paramType	参数类型

@ApiResponse

属性名称	备注
code	http的状态码
message	描述
response	默认响应类 Void
reference	参考ApiOperation中配置
responseHeaders	参考 ResponseHeader 属性配置说明
responseContainer	参考ApiOperation中配置

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
 
 
@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"
 
 
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值
 
 
@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类
 
 
@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

麦田的一米阳光

关注

2
点赞
踩
4

收藏

觉得还不错? 一键收藏
1
评论
关于springmvc4整合swagger2配置和jar依赖

jar依赖可从从https://mvnrepository.com/网站进行下载或者mavne 导入<dependency> <groupId>org.codehaus.jackson</groupId> <artifactId>jackson-mapper-asl</artifactId> <version...
复制链接

扫一扫