【原创】Sagger使用

Swagger使用

1. Spring MVC配置文件中的配置

<mvc:annotation-driven/>

<context:component-scan base-package="com.demo"/>

设置使用注解的类所在的jar包,只加载controller类

<mvc:default-servlet-handler />

使用 Swagger Restful API文档时，添加此注解

2. maven依赖

<properties>

<spring.version>4.2.6.RELEASE</spring.version>

<servlet.version>3.1.0</servlet.version>

<swagger2.version>2.5.0</swagger2.version>

</properties>

<dependencies>

<!-- swagger开始  -->

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>${swagger2.version}</version>

</dependency>

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>${swagger2.version}</version>

</dependency>

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-staticdocs</artifactId>

<version>${swagger2.version}</version>

</dependency>

<!--  swagger结束  -->

<!--spring-->

<dependency>

<groupId>org.springframework</groupId>

<artifactId>spring-core</artifactId>

<version>${spring.version}</version>

</dependency>

<dependency>

<groupId>org.springframework</groupId>

<artifactId>spring-web</artifactId>

<version>${spring.version}</version>

</dependency>

<dependency>

<groupId>org.springframework</groupId>

<artifactId>spring-webmvc</artifactId>

<version>${spring.version}</version>

</dependency>

<dependency>

<groupId>org.springframework</groupId>

<artifactId>spring-beans</artifactId>

<version>${spring.version}</version>

</dependency>

<dependency>

<groupId>org.springframework</groupId>

<artifactId>spring-context</artifactId>

<version>${spring.version}</version>

</dependency>

<dependency>

<groupId>org.springframework</groupId>

<artifactId>spring-context-support</artifactId>

<version>${spring.version}</version>

</dependency>

<!--web-->

<dependency>

<groupId>javax.servlet</groupId>

<artifactId>javax.servlet-api</artifactId>

<version>${servlet.version}</version>

<scope>provided</scope>

</dependency>

</dependencies>

3. Swagger注解配置

@RequestMapping(value = "/add", method = RequestMethod.POST)

@ApiOperation(value = "添加用户", notes = "增加用户")

public Result<UserVo> add(@ApiParam(name = "userName",value = "用户昵称",required = true)@RequestParam(name = "userName",required = true)String userName,

@ApiParam(name = "mobile",value = "手机",required = true)@RequestParam(name = "mobile",required = true)String mobile,

@ApiParam(required = true, name = "email", value = "邮箱") @RequestParam(name = "email", required = true) String email ) {

UserVo userVo=new UserVo();

userVo.setUserId(System.currentTimeMillis());

userVo.setUserName(userName);

return new Result<UserVo>(Constants.SUCCESS,Constants.MSG_SUCCESS,userVo);

}

@ApiOperation(value = "创建用户", notes = "根据UserVo对象创建用户")

@RequestMapping(value = "/create", method = RequestMethod.POST)

public String postUser(@ApiParam(required = true, name = "userVo", value = "实体UserVo") @RequestBody UserVo userVo) {

return "success";

}

@RequestMapping(value = "/getUser", method = RequestMethod.GET)

@ApiOperation(value = "获取用户", notes = "根据UserVo获取用户")

@ResponseBody

public Result<UserVo> getUser() {

UserVo userVo=new UserVo();

userVo.setUserId(System.currentTimeMillis());

userVo.setUserName("UserName");

return new Result<UserVo>(Constants.SUCCESS,Constants.MSG_SUCCESS,userVo);

}

SwaggerConfig类编写示例

@Configuration

@EnableSwagger2

public class SwaggerConfig {

@Bean

public Docket userApi() {

return new Docket(DocumentationType.SWAGGER_2)

.groupName("用户")

.select()  // 选择那些路径和api会生成document

.apis(RequestHandlerSelectors.basePackage("com.zyx.controller"))

.paths(PathSelectors.any()) // 对所有路径进行监控

.build()

.apiInfo(userInfo());

}

private ApiInfo userInfo() {

ApiInfo apiInfo = new ApiInfo("用户相关接口",//大标题

"用户有关的接口，包括增加删除用户",//小标题

"0.1",//版本

"杭州",

new Contact("zyx", "", ""),// 作者

"swagger url",//链接显示文字

""//网站链接

);

return apiInfo;

}

@Bean

public Docket otherApi() {

return new Docket(DocumentationType.SWAGGER_2)

.groupName("其它")

.select()  // 选择那些路径和api会生成document

.apis(RequestHandlerSelectors.basePackage("com.zyx.controller"))

.paths(PathSelectors.any()) // 对所有路径进行监控

.build()

.apiInfo(otherInfo());

}

private ApiInfo otherInfo() {

ApiInfo apiInfo = new ApiInfo("其它相关接口",//大标题

"其它有关的接口，包括增加删除其它",//小标题

"0.1",//版本

"杭州",

new Contact("zyx_other", "", ""),// 作者

"点击",//链接显示文字

""//网站链接

);

return apiInfo;

}

}

注:将SwaggerConfig在Spring注入管理 <bean class="com.demo.config.SwaggerConfig"/>

@ApiModel(value = "用户信息")

public class UserVo {

@ApiModelProperty(value = "用户id", required = true)

private long userId;

@ApiModelProperty(value = "昵称", required = true)

private String userName;

public long getUserId() {

return userId;

}

public void setUserId(long userId) {

this.userId = userId;

}

public String getUserName() {

return userName;

}

public void setUserName(String userName) {

this.userName = userName;

}

}

4. 界面展示

在浏览器输入地址：http://localhost:8080/swagger-ui.html