springboot-Swagger集成-易微帮

Swagger Codegen：通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。
Swagger UI：提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。
Swagger Editor：基于浏览器的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
Swagger Inspector：感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。
Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

3、Springfox介绍

由于 Spring的流行，Marty Pitt编写了一个基于 Spring的组件 swagger-springmvc，用于将 Swagger集成到 SpringMVC中来，而 Springfox则是从这个组件发展而来。

通常 Spring Boot项目整合 Swagger2需要用到两个依赖：springfox-swagger2和springfox-swagger-ui，用于自动生成swagger文档。

springfox-swagger2：这个组件的功能用于帮助我们自动生成描述API的json文件
springfox-swagger-ui：就是将描述API的json文件解析出来，用一种更友好的方式呈现出来
官方 UI很多人不太喜欢，觉得不太符合国人的使用习惯。通常我们通过引入 swagger-bootstrap-ui依赖来替换官方 UI。

4、Swagger常用注解

更多注解和使用说明，请查看Github：https://github.com/swagger-api/swagger-core/wiki/Annotations

@Api：用在请求的类上，表示对类的说明（不配置默认是按类名驼峰变下划线显示）
    value：该参数没什么意义，在UI界面上也看到，所以不需要配置"
    tags：说明该类的作用，可以在UI界面上看到的注解
    description：对api资源的描述
    basePath：基本路径
    position：如果配置多个Api 想改变显示的顺序位置
    produces：如 “application/json, application/xml”
    consumes：如 “application/json, application/xml”
    protocols：协议类型，如: http, https, ws, wss.
    authorizations：高级特性认证时配置
    hidden：配置为true ，将在文档中隐藏
@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value：说明方法的用途、作用
    tags：如果设置这个值、value的值会被覆盖
    notes：方法的备注说明
    description：对api资源的描述
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · div（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值
@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
    name：参数名
    value：参数说明
    required：是否必填
@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类
@ApiModel：用于pojo类上，描述一个Model的信息
（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候，比如使用@RequestBody这样的场景）
@ApiModelProperty：用在属性上，描述一个model的属性
@ApiIgnore：注解类、参数、方法，注解后将不在Swagger UI中显示

二，如何使用

1,导入maven依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>

2,创建SwaggerConfig.java

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

}

3,运行访问http://localhost:8082/swagger-ui.html进行测试

三，Swagger配置

在SwaggerConfig进行如下配置即可自定义Swagger配置

@Configuration
@EnableSwagger2   //开启Swagger2
public class SwaggerConfig{
  @Bean
  public Docket docket(){

    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
  }
  private ApiInfo apiInfo(){
    //作者信息
    Contact contact = new Contact("张三", "codekitty.cn:8000", "2983394967");

    return new ApiInfo("codekitty's Swagger API Documentation", "千里之行，始于足下", "1.0", "codekitty.cn:8000",contact , "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
  }
}

四，Swagger扫描接口

Docket(DocumentationType.SWAGGER_2).select()

new Docket(DocumentationType.SWAGGER_2)
  .apiInfo(apiInfo())
  .enable(b)//是否启用Swagger，false则不启用
  .select()
  //RequestHandlerSelectors,配置要扫描接口的方式
  //basePackage，指定扫描包
  //                .apis(RequestHandlerSelectors.any()),扫描全部
  //                .apis(RequestHandlerSelectors.none()),不扫描
  //                withMethodAnnotation(GetMapping.class)) //扫描类上的注解
  //                withClassAnnotation(GetMapping.class)) //扫描方法上的注解
  .apis(RequestHandlerSelectors.basePackage("com.controller"))
  //Path过滤路径
  //                .paths(PathSelectors.ant("/com/**"))

  .build();

实现开发环境中使用Swagger，运行上线环境中不使用Swagger

public Docket docket(Environment environment){
//设置要显示的Swagger环境
Profiles profiles = Profiles.of("dev","test");
//获取项目的环境：判断是否处在自己设定的环境中
boolean flag = environment.acceptsProfiles(profiles);
}

在properties中选择使用的环境,将flag传入Enable()

`3`，通过`groupName("")`配置多个Docket，(在多人开发中，每个开发者配置一个自己的Swagger，方便管理)

@Bean
public Docket docket1(){
  return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
  return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(){
  return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}

五，实体配置

1、新建一个实体类

@ApiModel("用户实体")
public class User {
   @ApiModelProperty("用户名")
   public String username;
   @ApiModelProperty("密码")
   public String password;
}

2，只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：

@RequestMapping("/getUser")
public User getUser(){   
	return new User();
}

注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。

@ApiModel为类添加注释

@ApiModelProperty为类属性添加注释

3，我们也可以给请求的接口配置一些注释

@ApiOperation("张三的接口")
@PostMapping("/zhangsan")
@ResponseBody
public String zhangsan(@ApiParam("这个名字会被返回")String username){
   return username;
}

这样的话，可以给一些比较难理解的属性或者接口，增加一些配置信息，让人更容易阅读！

相较于传统的Postman或Curl方式测试接口，使用swagger简直就是傻瓜式操作，不需要额外说明文档(写得好本身就是文档)而且更不容易出错，只需要录入数据然后点击Execute，如果再配合自动化框架，可以说基本就不需要人为操作了。

Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。当然了，提醒下大家在正式环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运行时内存。

六，常用注解

Swagger的所有注解定义在io.swagger.annotations包下

下面列一些经常用到的，未列举出来的可以另行查阅说明：

Swagger注解    简单说明
@Api(tags = “xxx模块说明”)    作用在模块类上
@ApiOperation(“xxx接口说明”)    作用在接口方法上
@ApiModel(“xxxPOJO说明”)    作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)    作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)    作用在参数、方法和字段上，类似@ApiModelProperty

七，其他皮肤

1、默认的访问 http://localhost:8080/swagger-ui.html

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

2、bootstrap-ui 访问 http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

3、Layui-ui 访问 http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>

4、mg-ui 访问 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>

springboot-Swagger集成

一、Swagger概述

1、Swagger简介

2、Swagger主要提供了几种开源工具

3、Springfox介绍

4、Swagger常用注解

二，如何使用

1,导入maven依赖

2,创建SwaggerConfig.java

3,运行访问http://localhost:8082/swagger-ui.html进行测试

三，Swagger配置

四，Swagger扫描接口

Docket(DocumentationType.SWAGGER_2).select()

实现开发环境中使用Swagger，运行上线环境中不使用Swagger

`3`，通过`groupName("")`配置多个Docket，(在多人开发中，每个开发者配置一个自己的Swagger，方便管理)

五，实体配置

1、新建一个实体类

2，只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：

3，我们也可以给请求的接口配置一些注释

六，常用注解

七，其他皮肤

1、默认的访问 http://localhost:8080/swagger-ui.html

2、bootstrap-ui 访问 http://localhost:8080/doc.html

3、Layui-ui 访问 http://localhost:8080/docs.html

4、mg-ui 访问 http://localhost:8080/document.html

网站公告

今日签到

热门文章

最新发布

springboot-Swagger集成

一、Swagger概述

1、Swagger简介

2、Swagger主要提供了几种开源工具

3、Springfox介绍

4、Swagger常用注解

二，如何使用

1,导入maven依赖

2,创建SwaggerConfig.java

3,运行访问http://localhost:8082/swagger-ui.html进行测试

三，Swagger配置

四，Swagger扫描接口

Docket(DocumentationType.SWAGGER_2).select()

实现开发环境中使用Swagger，运行上线环境中不使用Swagger

3，通过groupName("")配置多个Docket，(在多人开发中，每个开发者配置一个自己的Swagger，方便管理)

五，实体配置

1、新建一个实体类

2，只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：

3， 我们也可以给请求的接口配置一些注释

六 ，常用注解

七，其他皮肤

1、默认的 访问 http://localhost:8080/swagger-ui.html

2、bootstrap-ui 访问 http://localhost:8080/doc.html

3、Layui-ui 访问 http://localhost:8080/docs.html

4、mg-ui 访问 http://localhost:8080/document.html

网站公告

今日签到

热门文章

最新发布

`3`，通过`groupName("")`配置多个Docket，(在多人开发中，每个开发者配置一个自己的Swagger，方便管理)

3，我们也可以给请求的接口配置一些注释

六，常用注解

1、默认的访问 http://localhost:8080/swagger-ui.html