添加Swagger2依賴

在pom.xml中加入Swagger2的依賴

<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>

創(chuàng)建Swagger2配置類

在Application.java同級(jí)創(chuàng)建Swagger2的配置類Swagger2。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("你自己的外部接口包名稱"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("詞網(wǎng)Neo4j RESTful APIs")
                .description("The Neo4j RESTful APIs description/")
                .termsOfServiceUrl("")
                .contact("李慶海")
                .version("5.0")
                .build();
    }
}

添加文檔內(nèi)容

在完成了上述配置后，其實(shí)已經(jīng)可以生產(chǎn)文檔內(nèi)容，但是這樣的文檔主要針對(duì)請求本身，而描述主要來源于函數(shù)等命名產(chǎn)生，對(duì)用戶并不友好，我們通常需要自己增加一些說明來豐富文檔內(nèi)容。

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
/**
 * 系統(tǒng)用戶Controller
 * 
 * @author 李慶海
 *
 */
@Api(value = "系統(tǒng)用戶接口", tags = "系統(tǒng)管理")
@RestController
@RequestMapping("/v3/edu/users")
public class UserController {

    @Autowired
    private UserService userService;

    /**
     * 添加用戶，注冊
     * 
     * @param loginName
     *            登錄賬號(hào)
     * @param userName
     *            用戶名稱
     * @param password
     *            登錄密碼
     * @param roleId
     *            用戶角色
     * @return
     * @throws ResourceExistsException
     */
    @ApiOperation(value = "添加用戶")
    @PostMapping("/")
    public JsonResult create(
            @ApiParam(name = "loginName", value = "登錄賬號(hào)", required = true) @RequestParam(required = true) @RequestBody String loginName,
            @ApiParam(name = "userName", value = "用戶名稱", required = true) @RequestParam(required = true) @RequestBody String userName,
            @ApiParam(name = "password", value = "登錄密碼", required = true) @RequestParam(required = true) @RequestBody String password,
            @ApiParam(name = "roleId", value = "用戶角色編號(hào)", required = true) @RequestParam(required = true) @RequestBody String roleId)
            throws ResourceExistsException {
        boolean exists = this.userService.exists(loginName);
        if (exists) {
            throw new ResourceExistsException(loginName);
        }
        User user = userService.create(loginName, password, userName, roleId);
        return new JsonResult(user);
    }
}

查看API

啟動(dòng)Spring Boot程序，訪問：http://localhost:8080/swagger-ui.html

微信截圖_20180106154957.png

API文檔訪問與調(diào)試

Swagger除了查看接口功能外，還提供了調(diào)試測試功能，我們可以點(diǎn)擊上圖中右側(cè)的Model Schema（黃色區(qū)域：它指明了數(shù)據(jù)結(jié)構(gòu)），此時(shí)Value中就有了user對(duì)象的模板，我們只需要稍適修改，點(diǎn)擊下方Try it out！按鈕，即可完成了一次請求調(diào)用！可以通過幾個(gè)GET請求來驗(yàn)證之前的POST請求是否正確。