Swagger整理笔记

swagger是一个规范和完整的框架 , 用于生成 , 描述 , 调用和可视化RESTful风格的Web服务.

1. 及时性 (接口变更后 , 能够及时准确地通知相关的前后端开发人员)
2. 规范性(并且保证接口的规范性,如接口的地址 , 请求方式,参数及响应格式和错误信息)
3. 一致性(接口信息一致 , 不会出现因开发人员拿到的文档版本不一致,而出现分歧)
4. 可测性(直接在接口文档上进行测试,以方便理解业务)

一.swagger导入依赖

 <!--swagger-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
<!-- 返回fastjson格式-->
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>fastjson</artifactId>
    </dependency>

二.swagger常用注解

• @APi : 修饰整个类 , 描述Controller的作用 ,表示权限 , 提供者 , 消费者名称.
• @ApiOperation: 描述一个类 或者一个接口 的方法
• @ApiParam: 描述接收的单个参数的情况,如参数名称 , 类型.
• @ApiImplicitParam: 对单个参数做说明.和ApiParam注解类似
  • name: 指定参数名称
  • dataType : 指定参数类型
  • ParamType:
    • query: 作为普通参数类型时 @RequestParam
    • header: 加入@RequestHeader注解
    • path : 加@PathVariable注解
    • body: 加@RequestBody注解
• @ApiImplicitParams: 在方法传入多个参数时,可以用此注解接收
• @ApiModel: 用对象来接收参数时,描述pojo类的信息.标注在pojo类上.常和@RequestBody一起使用
• @ApiModelProperty : 用对象接收参数时 , 描述pojo对象中每个属性的信息,标注在pojo对象的属性或者方法上.
• @ApiRespnse:对返回值进行说明
• @ApiRespnses: 可以描述多个ApiRespnse 的响应信息.

三.swagger配置类

@Configuration
@EnableSwagger2 //配置Swagger2注解
public class Swagger2Config {

    //开发阶段 测试阶段 上线阶段
    //getDocket管理员组
    @Bean
    public Docket getAdminDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("管理员组")//设置组标题
                .apiInfo(getAdminInfo())//添加该群组的详细信息,包括管理员信息等
                .select()
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))//扫描admin管理员里的包 只扫描该路径下的页面
                .build();
    }

    public ApiInfo getAdminInfo(){//定义组的详细信息方法
        return new ApiInfoBuilder()
                .title("管理员系统接口文档")
                .description("这是一个文档")
                .version("1.0")
                .contact(new Contact("jake","http://www.baidu.com","123567@163.com"))
                .build();
    }

    
    //两个方法一般成对使用有几个群组就有几对方法.
}