Swagger在项目中的应用

纯手打……

前后端分离模式下，简化对接，提交效率

对于后端开发人员，使用swagger维护在线接口文档

spring集成了swagger，形成Spring-swagger项目

实际使用：

1：引入依赖：

        
        
            io.springfox
            springfox-swagger2
            2.9.2
        
        
        
            com.github.xiaoymin
            swagger-bootstrap-ui
            RELEASE
        
        
        
            io.swagger
            swagger-annotations
            1.5.22
        
        
            io.swagger
            swagger-models
            1.5.22
        

2 spring集成配置

/**
 * swagger
 *
 * @author l
 * @date 20190820
 */
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    /**
     * 创建Docket
     */
    @Bean
    public Docket createApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("api-user文档")
                // 去掉swagger默认的状态码
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.api.web.swagger"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 构造ApiInfo
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("这是swagger的title")
                .description("这是swagger的描述")
                .version("1.0.0")
                .contact(new Contact("张三", "", ""))
                .build();
    }
}

此时，即可访问 http://{ip}:{port}/doc.html

3 controller

/**
 * 用户
 *
 * @author l
 * @date 20190820
 */
@Slf4j
@RestController
@RequestMapping(value = "/api/user")
@Api(tags = "用户相关")
public class UserController {

    static Map map = new HashMap(){{
        put(1, new User().setId(1).setName("张三").setPhone("13566669999"));
        put(2, new User().setId(2).setName("李四").setPhone("15899996666"));
    }};

    /**
     *  查询用户
     */
    @GetMapping("/info")
    /** 定义swagger中接口说明 */
    @ApiOperation(value="根据id查询用户",notes="id必填，rest方式",consumes = "application/x-www-form-urlencoded")
    /** 定义swagger中的请求参数 */
    @ApiImplicitParams({
        @ApiImplicitParam(name="id",value="id",required=true,paramType="query",dataType = "int")
    })
    /** 定义接口返回信息 */
    @ApiResponses({@ApiResponse(code = 200,message = "OK")})
    public Result info(Integer id){
        log.info("查询id={}的用户", id);
        return Result.ok(map.get(id));
    }

    /**
     *  查询所有用户
     *      swagger中的接口顺序是以uri的字母顺序生成
     */
    @GetMapping("/all")
    @ApiOperation(value="查询所有用户")
    public Result> getAll(){
        List list = new ArrayList<>();
        for (Map.Entry entry : map.entrySet()) {
            list.add(entry.getValue());
        }
        return Result.ok(list);
    }

}

4 实体类user

/**
 *  用户
 */
@Data
@Accessors(chain = true)
@ApiModel(description = "用户实体")
public class User {
    @ApiModelProperty(value = "主键")
    private Integer id;
    @ApiModelProperty(value = "姓名")
    private String name;
    @ApiModelProperty(value = "手机号")
    private String phone;
}

5 实体类result

/**
 *  返回实体
 */
@Data
@Accessors(chain = true)
@ApiModel(description = "返回实体")
public class Result {
    @ApiModelProperty(value = "状态码")
    private Integer code;
    @ApiModelProperty(value = "返回信息")
    private String message;
    @ApiModelProperty(value = "返回数据")
    private T datas;

    public static  Result ok(T t){
        return new Result().setCode(200).setMessage("ok").setDatas(t);
    }
}

6 具体效果图：

主页：

 

接口一：

 

接口二：

 

7 注解说明：

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，UI界面显示"
    value="UI界面不显示，无用"

@ApiOperation：用在请求的接口上，解释说明
    value="对接口的说明"
    notes="接口的描述"

@ApiImplicitParams：用在请求的接口上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="int"       
        defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
    @ApiModelProperty：用在属性上，描述响应类的属性

 

完.

 

 

参考https://www.jianshu.com/p/f30e0c646c63