Swagger

许喜朝

发布于 2021-01-14 14:07:18

7710

发布于 2021-01-14 14:07:18

文章被收录于专栏：生如夏花的个人博客生如夏花的个人博客

Swagger

出现的问题

自从前后端分离以后，前端后端的开发就分离开来

那么前端后端如何来交流呢？最早的解决办法就是写好开发文档以后前端后端在进行开发

这样就又出现了一个问题，

如果有需求被修改了

那么怎样在能及时的在开发文档中修改，让前端后端都知晓呢？

Swagger简介

号称世界上最流行的Api框架
RestFul Api文档自动生成工具=>文档与Api定义同步更新
直接运行，可以在线测试Api接口

集成springboot

新建工程

新建springboot工程，加入spring-web依赖

引入相关依赖

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

配置类SwaggrConfig

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

访问swagger-ui,http://localhost:8080/swagger-ui.html

swagger3目前不能使用这种方法访问

自定义配置Swagger

当然你不配置也是可以使用的，在配置类开启了swagger的前提下

@Configuration
@EnableSwagger2//开启swagger2
public class SwaggerConfig {
    //配置Swagger的Docket示例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xu.swagger.controller"))
                .build();
        //.apis：扫描路径
        //      RequestHandlerSelectors：配置要扫描的接口方式
        //      basePackage:扫描指定包
        //      any:全部扫描
        //      none：不扫描
        //      withClassAnnotation:扫描类上的注解
        //      withMethodAnnotation:扫描方法上的注解

        //.enable：是否开启swagger默认值为true
    }
    //配置swagger信息apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("生如夏花","","2414506319@qq.com");
        return new ApiInfo(
                "生如夏花api",
            "生如夏花之绚烂，死如秋叶之静美",
            "1.0",
            "urn:tos",
            contact,
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList());
    }
}

配置api文档分组

@Configuration
@EnableSwagger2//开启swagger2
public class SwaggerConfig {



    //配置Swagger的Docket示例
    @Bean
    public Docket docket(Environment environment){
        Profiles of = Profiles.of("dev","test");
        boolean b = environment.acceptsProfiles(of);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("生如夏花")//配置分组
                .enable(b)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xu.swagger.controller"))
    }
    //配置swagger信息apiInfo

    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("生如夏花","","2414506319@qq.com");
        return new ApiInfo(
                "生如夏花api",
            "生如夏花之绚烂，死如秋叶之静美",
            "1.0",
            "urn:tos",
            contact,
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList());
    }
}

配置多个分组

swagger 返回多个Docket 一个Docket示例就是一个分组

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("a");
}

@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("b");
}
//设置了两个组

提问

如何在开发环境和测试环境下开启swagger在生产环境下关闭swagger

@Configuration
@EnableSwagger2//开启swagger2
public class SwaggerConfig {
    //配置Swagger的Docket示例
    @Bean
    public Docket docket(Environment environment){
        Profiles of = Profiles.of("dev","test");
      //判断是否是dev和test 返回值类型boolean
        boolean b = environment.acceptsProfiles(of);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(b)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xu.swagger.controller"))
                .build();
   
    }
  
}

当然也可以采用读取配置文件然后判断处于什么类型来解决

常用注解

注解	作用
@Api	用于标注一个Controller
@ApiParam	作用于请求方法上，定义api参数的注解（如这个方法是干什么的）
@ApiImplicitParam	对单个参数的说明（如post请求需要一个password，使用此注解可以对password说明）
@ApiImplicitParams	用在请求的方法上，包含一组参数说明
@ApiResponses、@ApiResponse	进行方法返回对象的说明
@ApiModel	用于描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）。
@ApiModelProperty	用来描述一个Model的属性