swagger2 ui 自动生成api文档,就节省了编写接口测试和文档的工作,非常方便
下面以集成融云IM api 为例,展示如何配置swagger2
pom.xml
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.4.3.RELEASE</version>
<relativePath/>
</parent>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.2.4</version>
</dependency>
<dependency>
<groupId>commons-codec</groupId>
<artifactId>commons-codec</artifactId>
<version>1.4</version>
</dependency>
<!--
7 devtools可以实现页面热部署(即页面修改后会立即生效,这个可以直接在application.properties文件中配置spring.thymeleaf.cache=false来实现),
8 实现类文件热部署(类文件修改后不会立即生效),实现对属性文件的热部署。
9 即devtools会监听classpath下的文件变动,并且会立即重启应用(发生在保存时机),注意:因为其采用的虚拟机机制,该项重启是很快的
10 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-devtools</artifactId>
<optional>true</optional><!-- optional=true,依赖不会传递,该项目依赖devtools;之后依赖myboot项目的项目如果想要使用devtools,需要重新引入 -->
</dependency>
</dependencies>
application.properties
#项目contextPath,一般在正式发布版本中,我们不配置
#server.context-path=/springboot
# 错误页:指定发生错误时,跳转的URL。请查看BasicErrorController。
#server.error.path=/error
# 服务端口,默认为8080
server.port=9090
# session最大超时时间(分钟),默认为30
server.session-timeout=60
# 该服务绑定IP地址,启动服务器时如本机不是该IP地址则抛出异常启动失败,只有特殊需求的情况下才配置
#server.address=192.168.1.112
SwaggerConfig
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
ApiInfo apiInfo = new ApiInfoBuilder()
.title("ShiQiqao_YiY_即时通信API")
.description("客户端与服务端接口文档")
.termsOfServiceUrl("http://localost:8080")
.contact("xiaoyuzhou")
.version("1.0.0")
.build();
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.select()
.apis(RequestHandlerSelectors.basePackage("com.vc.im.rongcloud.api.web.controller"))
.paths(PathSelectors.any())
.build();
}
}
Application
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.web.servlet.ServletComponentScan;
@SpringBootApplication
@ServletComponentScan
public class Application {
public static void main(String[] args) throws Exception {
SpringApplication.run(Application.class, args);
}
}
controller
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
@RestController
@CrossOrigin
@RequestMapping(value = "/im")
public class ApiController {
// 创建线程安全的Map
static RongCloud rongCloud = RongCloud.getInstance(AppConstants.APPKEY, AppConstants.APPSECRET);
// ************************User********************
@ApiOperation(value = "获取Token", notes = "")
@ApiImplicitParams(value = {
@ApiImplicitParam(name = "userId", value = "用户Id", required = true, paramType = "query", dataType = "String"),
@ApiImplicitParam(name = "name", value = "姓名", required = true, paramType = "query", dataType = "String"),
@ApiImplicitParam(name = "portraitUri", value = "用户头像地址", required = true, paramType = "query", dataType = "String")
})
@RequestMapping(value = {"/user/token"}, method = RequestMethod.GET)
public String getToken(@RequestParam String userId,@RequestParam String name,@RequestParam String portraitUri) throws Exception {
TokenResult userGetTokenResult = rongCloud.user.getToken(userId, name, portraitUri);
return userGetTokenResult.toString();
}
//...
}
访问
http://localhost:9090/swagger-ui.html
效果
还可以填写http参数 进行测试