Spring cloud 集成Swagger

一、Swagger 简介

Swagger是基于REST APIs 定义一个标准的与语言无关的接口。通过查看这些接口了解到该请求的参数和返回结果。Swagger还提供了Web 界面Swagger UI，可以通过SwaggerUI进行测试接口。

二、Spring集成Swagger

1.导入Swagger相关的POM

<properties>
        <springfox.version>2.7.0</springfox.version>
</properties>   
<dependencies>
        <dependency>    
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <dependency>    
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>com.mangofactory</groupId>
            <artifactId>swagger-springmvc</artifactId>
            <version>1.0.2</version>
        </dependency>
    </dependencies>

springfox-swagger2 ：Spring 集成Swagger 开箱即用的相关配置包
springfox-swagger-ui ： web界面的包
swagger-springmvc ：Swagger 使用的注解和相关Spring MVC 的配置

2.Swagger 的配置类

@EnableSwagger2  //启动Swagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.web.controller")) //扫描文档注解的包路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试") //标题
                .description("Create by Alan Di") 描述
                .version("1.0")
                .build();
    }
}

这里我们需要注意一下@EnableSwagger2，我们可以通过查看这个注解可以知道是使用Swagger2DocumentationConfiguration配置类来进行配置，而Swagger2DocumentationConfiguration集成了Spring MVC的配置，因为springfox-swagger-ui是一个web，需要进行swagger-ui.html的映射配置。如果我们使用了 @EnableSwagger2的时候我们就不需要使用@EnableWebMvc注解，如果2个同时使用的情况下会导致springfox-swagger-ui的/swagger-ui.html界面不可以访问。

3.注解配置

/**
 * 角色
 * @author CalvinDai
 *
 * 2017年9月29日
 */
@Api(description="角色控制器")  
@Controller("/role")
public class RoleController {

    /**
     * 查询角色
     */
    @ApiOperation(tags="获取所有角色信息",value="获取所有角色信息")  
    @GetMapping("/listRole")
    @ResponseBody
    public Response listRole(@RequestBody ListRoleReq listRoleReq){
        
        return Response.success("");
    }
}

@ApiModel("获取角色信息请求参数")
public class ListRoleReq {
    /**
     * 签名
     */
    @ApiModelProperty(value="签名",required=true)
    private String signatures;
    /**
     * 系统
     */
    @ApiModelProperty(value="系统名",required=true)
    private String system;
    /**
     * 用户ID
     */
    @ApiModelProperty(value="用户Id",required=true)
    private String userId;
    public String getSignatures() {
        return signatures;
    }
    public void setSignatures(String signatures) {
        this.signatures = signatures;
    }
    public String getSystem() {
        return system;
    }
    public void setSystem(String system) {
        this.system = system;
    }
    public String getUserId() {
        return userId;
    }
    public void setUserId(String userId) {
        this.userId = userId;
    }
    
    
}

/**
 * 请求返回结果
 * @author CalvinDai
 *
 * 2017年9月29日
 */
@ApiModel("响应结果")
public class Response {
    /**
     * 消息
     */
    @ApiModelProperty(value="返回消息")
    private String message;
    /**
     * 响应码
     */
    @ApiModelProperty(value="响应码")
    private int code;
    
    /**
     * 返回数据
     */
    @ApiModelProperty(value="返回数据")
    private Map<String,Object> data;
    
    /**
     * 添加返回信息
     * @param key
     * @param data
     */
    public void putData(String key ,Object data){
        this.data.put(key, data);
    }
    /**
     * 成功
     */
    public static  Response  success(String successMessage){
        Response response = new Response();
        response.setCode(ResponseConstant.SUCCESS);
        response.setMessage(successMessage);
        return response;
    }
    /**
     * 失败
     * @param errorMessage
     * @return
     */
    public static Response fail(String errorMessage){
        Response response = new Response();
        response.setCode(ResponseConstant.ERROR);
        response.setMessage(errorMessage);
        return response;
    }
    
    
    public String getMessage() {
        return message;
    }
    public void setMessage(String message) {
        this.message = message;
    }
    public int getCode() {
        return code;
    }
    public void setCode(int code) {
        this.code = code;
    }
    public Map<String, Object> getData() {
        return data;
    }
    public void setData(Map<String, Object> data) {
        this.data = data;
    }
}

@ApiModel :请求或者响应的Model
@ApiModelProperty :Model的属性
@ApiOperation:可以请求的方法
其他注解自己慢慢尝试。

4.访问

请求访问的地址：http://localhost:8181/swagger-ui.html

QQ图片20171009123038.png

Example Value ：返回的JSON格式或者请求的JSON格式
parameters 中的Value 为请求的测试参数，可以点击Parameters中的Example Value 请求实例，就会复制一份请求参数到Value中