springboot-restful api-swagger2 ui-实战

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# 服务端口，默认为8080server.port=9090# session最大超时时间(分钟)，默认为30server.session-timeout=60# 该服务绑定IP地址，启动服务器时如本机不是该IP地址则抛出异常启动失败，只有特殊需求的情况下才配置#server.address=192.168.1.112

SwaggerConfig

@Configuration@EnableSwagger2public 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@ServletComponentScanpublic 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参数 进行测试