Swagger在项目中的应用

纯手打……

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

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

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

实际使用：

1：引入依赖：

        <!-- swagger核心组件，在代码配置swagger时会依赖到它 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- swagger的用户界面，用于展示api接口文档 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>RELEASE</version>
        </dependency>
        <!--增加两个配置目的：访问swagger后台报错处理-->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.22</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>

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<Integer, User> map = new HashMap<Integer, User>(){{
        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<User> info(Integer id){
        log.info("查询id={}的用户", id);
        return Result.ok(map.get(id));
    }

    /**
     *  查询所有用户
     *      swagger中的接口顺序是以uri的字母顺序生成
     */
    @GetMapping("/all")
    @ApiOperation(value="查询所有用户")
    public Result<List<User>> getAll(){
        List<User> list = new ArrayList<>();
        for (Map.Entry<Integer, User> 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<T> {
    @ApiModelProperty(value = "状态码")
    private Integer code;
    @ApiModelProperty(value = "返回信息")
    private String message;
    @ApiModelProperty(value = "返回数据")
    private T datas;

    public static <T> Result<T> ok(T t){
        return new Result<T>().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：用在属性上，描述响应类的属性

 

另记录一通用版本：

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

 

 

完.

 

 

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