Swagger2 的使用

1，在pom 文件添加两个依赖，swagger依赖和swagger-ui的依赖。

<!--swagger-->

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

2，如果有代码生成器，在代码生成器中配置启用 swagger2。

 

3， 常用注解

    bean类

- @ApiModel()用于类 

    value–表示对象名 

    description–描述 

表示对类进行说明，用于参数用实体类接收 

 

- @ApiModelProperty()用于方法，字段 

    value–字段说明 

    name–重写属性名字 

    dataType–重写属性类型 

    required–是否必填 

    example–举例说明 

    hidden–隐藏

表示对model属性的说明或者数据操作更改 

    

    接口，类

 

- @Api()用于类；

    tags–表示说明 

    value–也是说明，可以使用tags替代 

    但是tags如果有多个值，会生成多个list

表示标识这个类是swagger的资源

 

- @ApiOperation()用于方法；

    value用于方法描述 

    notes用于提示内容 

    tags可以重新分组（视情况而用） 

表示一个http请求的操作

 

- @ApiParam()用于方法，参数，字段说明；

    name–参数名 

    value–参数说明 

    required–是否必填

表示对参数的添加元数据（说明或是否必填等）

 

 

 

- @ApiIgnore()用于类，方法，方法参数

表示这个方法或者类被忽略

- @ApiImplicitParam() 用于方法

表示单独的请求参数

- @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

 

 

 

4.swagger2接口分类配置

 

 

@Configuration

@EnableSwagger2

public class Swagger2Config {

 

    @Bean

    public Docket webApiConfig() {

        return new Docket(DocumentationType.SWAGGER_2)

                .groupName("webApi")

                .apiInfo(webApiInfo())// 调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容

                .select()//创建ApiSelectorBuilder对象

                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))//过滤掉admin接口

                .paths(Predicates.not(PathSelectors.regex("/error.*")))//过滤掉错误路径

                .build();

                //.useDefaultResponseMessages(false);//不使用默认的返回值

    }

 

    @Bean

    public Docket adminApiConfig() {

        return new Docket(DocumentationType.SWAGGER_2)

                .groupName("adminApi")

                .apiInfo(adminApiInfo())// 调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容

                .select()//创建ApiSelectorBuilder对象

                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))//过滤的接口

                .build();

    }

 

    private ApiInfo webApiInfo() {

        return new ApiInfoBuilder()

                .title("web-用户中心微服务API")//大标题

                .description("此文档描述了用户中心web端微服务API")//详细描述

                .version("1.0")//版本

                .contact(new Contact("Helen", "http://atguigu.com", "55317332@qq.com"))//作者

                .build();

    }

 

    private ApiInfo adminApiInfo() {

        return new ApiInfoBuilder()

                .title("后台管理-用户中心微服务API")//大标题

                .description("此文档描述了用户中心后台管理微服务API")//详细描述

                .version("1.0")//版本

                .contact(new Contact("Helen", "http://atguigu.com", "55317332@qq.com"))//作者

                .build();

    }

}