不会或不熟悉前端?没关系!集成Swagger轻松帮助你!
1.首先映入相关JAR包,我这里是maven项目,所以直接在pom文件引入。
<!--Swagger start-->
<!-- springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>
<!-- springfox-swagger2 dependencies -->
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>2.9.5</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.9.5</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>2.9.5</version>
</dependency>
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>15.0</version>
</dependency>
<dependency>
<groupId>com.fasterxml</groupId>
<artifactId>classmate</artifactId>
<version>1.1.0</version>
</dependency>
<!--swagger end-->
如果你的pom文件有引入和包含引入的包,注意排包 swagger有多个版本 ,不同版本注解也有差异,建议使用和本文相同的版本。
2.复制一下swaggger配置文件,放到项目中
package cn.sevendream.mmall.config;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
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;
/**
* ${DESCRIPTION}
*
* @author zhangxue
* @date 2018-10-30 下午5:02
*/
@Component
@Configuration
@EnableSwagger2
@EnableWebMvc
@ComponentScan("cn.sevendream.mmall.controller")
public class Swagger2Config {
@Bean
public Docket createAPI() {
return new Docket(DocumentationType.SWAGGER_2).forCodeGeneration(true).select().apis(RequestHandlerSelectors.any())
//过滤生成链接
.paths(PathSelectors.any()).build().apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
Contact contact=new Contact("Simon","https://blog.csdn.net/zx03070723","345623958@qq.com");
ApiInfo apiInfo = new ApiInfoBuilder().license("Apache License Version 2.0").title("Swagger 集成测试").description("Swagger API Teste").contact(contact).version("1.0").build();
return apiInfo;
}
}
3.dispatcher-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"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/mvc
http://www.springframework.org/schema/mvc/spring-mvc.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">
<mvc:annotation-driven>
<mvc:message-converters>
<bean class="org.springframework.http.converter.StringHttpMessageConverter">
<property name="supportedMediaTypes">
<list>
<value>text/plain;charset=UTF-8</value>
<value>text/html;charset=UTF-8</value>
</list>
</property>
</bean>
<bean class="org.springframework.http.converter.json.MappingJackson2HttpMessageConverter">
<property name="supportedMediaTypes">
<list>
<value>application/json;charset=UTF-8</value>
</list>
</property>
</bean>
</mvc:message-converters>
</mvc:annotation-driven>
<!--根据servlet请求,找到对应controller的对应方法-->
<context:component-scan base-package="cn.sevendream.mmall.controller"/>
<!-- 容器默认的DefaultServletHandler处理 所有静态内容与无RequestMapping处理的URL-->
<mvc:default-servlet-handler/>
<!--swagger相关-->
<context:component-scan base-package="springfox"/>
<mvc:annotation-driven />
<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>
</beans>
4.同步前三步,就配置好了 ,剩下的就是开始使用swagger注解,启动项目进行测试了。
先介绍下swagger的注解
常用注解:
- @Api()用于类;
表示标识这个类是swagger的资源
- @ApiOperation()用于方法;
表示一个http请求的操作
- @ApiParam()用于方法,参数,字段说明;
表示对参数的添加元数据(说明或是否必填等)
- @ApiModel()用于类
表示对类进行说明,用于参数用实体类接收
- @ApiModelProperty()用于方法,字段
表示对model属性的说明或者数据操作更改
- @ApiIgnore()用于类,方法,方法参数
表示这个方法或者类被忽略
- @ApiImplicitParam() 用于方法
表示单独的请求参数
- @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
以下是我项目中的示例。
@RequestMapping(value = "register", method = RequestMethod.POST)
@ApiOperation(value = "注册")
public ServerResponse<String> register(@RequestBody @ApiParam(value = "用户对象") User user{
return iUserService.register(user);
}
@RequestMapping(value = "check_valid", method = RequestMethod.POST)
@ApiOperation(value = "校验用户名/邮箱是否有效")
@ApiImplicitParams({@ApiImplicitParam(name = "value", value = "校验值", paramType = "query",
dataType = "string")
, @ApiImplicitParam(name = "type", value = "类型码值【username,email】",
paramType = "query", dataType = "string")} )
public ServerResponse<String> checkValid(@RequestParam("value") String value,
@RequestParam("type") String type) {
return iUserService.checkValid(value, type);
}
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "用户对象user",description = "用户对象user")
public class User {
@ApiModelProperty(value = "用户主键",hidden = true)
private Integer id;
@ApiModelProperty(value = "账号",name="username",example = "Simon")
private String username;
@ApiModelProperty(value = "密码",example = "111111")
private String password;
@ApiModelProperty(value = "邮箱",example = "111111@qq.com")
private String email;
@ApiModelProperty(value = "联系方式",example = "13811111111")
private String phone;
@ApiModelProperty(value = "问题",example = "我的名字")
private String question;
@ApiModelProperty(value = "答案",example = "Simon")
private String answer;
@ApiModelProperty(value = "角色",hidden = true)
private Integer role;
@ApiModelProperty(value = "创建时间")
private Date createTime;
@ApiModelProperty(value = "更新时间")
private Date updateTime;
}