Swagger 3.0快速入门

Swagger快速入门

• 一。Swagger简介
• • 1. 前后端分离
  • 2. Swagger引入
  • springfox-swagger 2
  • SpringFox 3.0.0 发布
  • swagger3.0 与配置差异：
• 具体使用教程如下
• • 1.导入依赖
  • 配置
  • 3.配置Swagger API信息
  • 4.修改默认API文档显示页面
  • 配置Swagger自定义扫描接口
  • 自定义扫描接口
  • 配置是否启动Swagger
  • Swagger只在生产环境下使用
  • 配置API文档分组
  • • 1. 设置默认组名
    • 2. 配置多个组
  • 配置Model实体类
  • • 只要我们的controoler层方法中，返回值中存在实体类，他就会被扫描到Swagger中
  • @ApiModel为类添加注释
  • @ApiModelProperty为类属性添加注释
  • 我们同样可以在Controller类和其中的方法上添加相应的注解
  • • @Api
    • @ApiOperation
    • @ApiParam--给参数上加上解释
  • 常用注解总结
  • • 总结: 发布的时候，记得关闭Swagger，可以通过生产环境设置来完成这一需求
  • swagger 3.0的swagger页面访问url
• 参考文章
• Swagger3增强插件----knife4j
• • Swagger3.0 异常：导致: For input string: ““

---

一。Swagger简介

1. 前后端分离

后端时代：前端只用管理静态页面；html等静态资源交给后端通过模板引擎进行渲染

前后端分离时代：

• 后端：控制层controller、服务层service、数据访问层dao
• 前端：前端控制层、视图层
• 前后端交互：通过API接口
• 前后端相对独立，松耦合，甚至可以部署在不同的服务器上
• 随之产生的问题：前后端联调，前端人员和后端人员无法做到及时协商，尽早解决

解决方案：

• 首先指定schema(计划)，实时更新最新的API，降低集成风险
• 早些年：指定word计划文档
• 前后端分离：
• 前端测试后端接口数据是否正确：postman
• 后端提供接口，需要实时更新最新的消息和改动

于是Swagger应运而生

---

2. Swagger引入

• 号称历史上最流行的api框架
• RestFul Api文档在线生成工具=》Api文档与Api定义同步更新
• 直接运行，可以在线测试Api接口
• 支持多种语言

---

springfox-swagger 2

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

• springfox-swagger2：这个组件的功能用于帮助我们自动生成描述API的json文件
• springfox-swagger-ui：就是将描述API的json文件解析出来，用一种更友好的方式呈现出来。

---

SpringFox 3.0.0 发布

此版本的亮点：

• Spring5，Webflux支持（仅支持请求映射，尚不支持功能端点）。
• Spring Integration支持。
• SpringBoot支持springfox Boot starter依赖性（零配置、自动配置支持）。
• 支持OpenApi 3.0.3。
• 零依赖。几乎只需要spring-plugin，swagger-core ，现有的swagger2注释将继续工作并丰富openapi3.0规范。

兼容性说明：

• 需要Java 8
• 需要（未在早期版本中测试）
• 需要SpringBoot 2.2+（未在早期版本中测试）

---

swagger3.0 与配置差异：

• 应用主类添加注解@EnableOpenApi (swagger2是@EnableSwagger2)
• swagger配置类，与 版本有差异，具体看下文
• 自定义一个配置类 ,看下文
• 访问地址：http://localhost:8080/swagger-ui/
  (版本访问的地址为http://localhost:8080/)

---

具体使用教程如下

---

1.导入依赖

Maven项目中引入springfox-boot-starter依赖：

<dependency>
    <groupId></groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

---

配置

spring:
  application:
    name: springfox-swagger
server:
  port: 8080
# ===== 自定义swagger配置 ===== #
swagger:
  enable: true
  application-name: ${}
  application-version: 1.0
  application-description: springfox swagger 3.0整合Demo
  try-host: http://localhost:${}

---

3.配置Swagger API信息

在Swagger提供的ui界面，其中的Swagger信息模块我们可以自定义信息内容
我们只需要在Swagger配置类SwaggerConfig中实例化Docket类队对象的bean实例，通过配置ApiInfo类的信息然后传入Docket的bean实例即可

---

4.修改默认API文档显示页面

@Configuration
@EnableOpenApi //开启Swagger3
public class SwaggerConfig {
    //配置Swagger的Docket的bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());//配置Swagger信息
    }

    //配置Swagger信息
    /*String title, String description,
     String version, String termsOfServiceUrl,
     Contact contact, String license,
     String licenseUrl,
     Collection<VendorExtension> vendorExtensions*/
    private ApiInfo apiInfo() {
        return new ApiInfo(
                "大忽悠项目",
                "大忽悠的Swagger API文档",
                "2.0",//版本信息
                "/m0_53157173",//团队信息的url
                new Contact("大忽悠", "/m0_53157173", "3076679680@"),//作者信息
                /*Contact(String name, String url, String email)*/
                "Apache 2.0",
                "/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }
}

---

配置Swagger自定义扫描接口

我们在这个ui界面中，可以看到扫描了两个controller接口；

• 一个是默认的/error请求，也就是我们启动springboot主程序未加配置默认访问8080端口的默认controller

• 剩余的就是我们自己再controller层写的请求映射了

---

自定义扫描接口

    //配置Swagger的Docket的bean实例
    @Bean
    public Docket docket()
    {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//配置Swagger信息
                .select()
                /**
                 * apis():指定扫描的接口
                 *  RequestHandlerSelectors:配置要扫描接口的方式
                 *       basePackage:指定要扫描的包
                 *       any:扫面全部
                 *       none:不扫描
                 *       withClassAnnotation:扫描类上的注解(参数是类上注解的class对象)
                 *       withMethodAnnotation:扫描方法上的注解(参数是方法上的注解的class对象)
                 */
                .apis(RequestHandlerSelectors.basePackage(""))
                /**
                 * paths():过滤路径
                 *  PathSelectors:配置过滤的路径
                 *      any:过滤全部路径
                 *      none:不过滤路径
                 *      ant:过滤指定路径:按照按照Spring的AntPathMatcher提供的match方法进行匹配
                 *      regex:过滤指定路径:按照String的matches方法进行匹配
                 */
                .paths(PathSelectors.any())
                .build();
    }

其中.select().是一套组合进行使用

只有被过滤筛选出来并且在指定包下面的请求路径才会显示在页面上

---

配置是否启动Swagger

我么通过Docket对象的.enable方法来配置swagger是否启动

    @Bean
    public Docket docket()
    {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//配置Swagger信息
                .enable(false)//enable是否启动swagger,如果为false,那么浏览器中无法访问swagger
                .select()
                .apis((""))
                .paths(())
                .build();
    }

---

Swagger只在生产环境下使用

• 首先要判断是不是开发环境，可以设置一个flag表示用来表示：flag=1即表示生产环境
• 然后将flag的值传给enable(flag)

首先在resources目录下新建两种springboot配置文件

开发环境：

=8081

正式环境：

=8082

然后在主配置文件中激活开发环境

=dev

然后我们到SwaggerConfig中的docket()方法中添加代码：

首先给该方法传一个参数Environment的实例

Environment environment

首先设置要配置的Swagger环境：这里可以添加多个环境

Profiles.of("dev", "test");

然后通过方法判断是否处在上一步设定的dev/test环境中，返回一个boolean的值，我们用flag接收

boolean flag = environment.acceptsProfiles(profiles);

然后修改enable中的参数为flag，即通过flag来判断是否开启Swagger

.enable(flag)//通过flag判断是否开启

完整代码：

@Configuration
@EnableOpenApi //开启Swagger3
public class SwaggerConfig {
    //配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment)
    {
        //设置要配置的Swagger环境
        Profiles p = Profiles.of("dev", "test");
        //通过判断是否处在自己设定的环境中
        boolean flag = environment.acceptsProfiles(p);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//配置Swagger信息
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage(""))
                .paths(PathSelectors.any())
                .build();
    }

    //配置Swagger信息
    private ApiInfo apiInfo() {
        return new ApiInfo(
                "大忽悠项目",
                "大忽悠的Swagger API文档",
                "2.0",//版本信息
                "/m0_53157173",//团队信息的url
                new Contact("大忽悠", "/m0_53157173", "3076679680@"),//作者信息
                /*Contact(String name, String url, String email)*/
                "Apache 2.0",
                "/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }
}

然后启动主程序测试：由于激活了dev开发环境，所以访问localhost:8081/

成功开启swagger，如果我们修改主配置文件，激活pro正式发布环境

=pro

再次重启主程序测试，访问端口8082对应的地址localhost:8082/

无法进入，因为pro环境不在我们配置的test/dev环境中，所以无法开启

---

配置API文档分组

1. 设置默认组名

可以看到，我们默认只有一个组且组名为default

我们可以在docket通过.groupName中设置组名

    @Bean
    public Docket docket(Environment environment)
    {
        //设置要配置的Swagger环境
        Profiles p = Profiles.of("dev", "test");
        //通过判断是否处在自己设定的环境中
        boolean flag = environment.acceptsProfiles(p);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//配置Swagger信息
                .enable(flag)
                .groupName("大忽悠")
                .select()
                .apis(RequestHandlerSelectors.basePackage(""))
                .paths(PathSelectors.any())
                .build();
    }

---

2. 配置多个组

上述我们成功修改了组名，但是只有一个组，如果我们想要多个组呢？
观察代码可以知道，一个Docket实例就对应着一个组，因此我们配置多个docket就对应着多个组

    @Bean
    public Docket docket1() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("大忽悠1号");
    }

    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("大忽悠2号");
    }

---

配置Model实体类

只要我们的controoler层方法中，返回值中存在实体类，他就会被扫描到Swagger中

@RestController
public class UserControoler
{
    //只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中
    @GetMapping("/User")
    public User showUser(User u)
    {
        return u;
    }
}

现在的问题是，页面显示出来的返回的User类，如果是非常复杂的情况下，没有注释就很难看懂，这样就有了注解来进行解释

---

@ApiModel为类添加注释

@ApiModelProperty为类属性添加注释

@NoArgsConstructor
@AllArgsConstructor
@Data
@ApiModel("用户实体类")
public class User
{
    @ApiModelProperty("姓名")
    String name;
    @ApiModelProperty("年龄")
    Integer age;
   @TableId(value="id",type = IdType.AUTO)
   @ApiModelProperty("主键id")
    Integer id;
    //字段添加填充内容
    @TableField(fill = FieldFill.INSERT)
    @ApiModelProperty("创建时间")
    private Date createTime;
    @TableField(fill = FieldFill.INSERT_UPDATE)
    @ApiModelProperty("修改时间")
    private Date updateTime;
    @Version
    @ApiModelProperty("版本，用于乐观锁")
    Integer version;
    //逻辑删除字段
    @TableLogic
    @ApiModelProperty("逻辑删除字段")
    private Integer deleted;
}

---

我们同样可以在Controller类和其中的方法上添加相应的注解

@Api

@ApiOperation

没加前:

加注解中…

@RestController
@Api(tags ="User数据交互")
public class UserControoler
{
    //只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中
    @GetMapping("/User")
    @ApiOperation("展示用户")
    public User showUser(User u)
    {
        return u;
    }
}

效果展示:

---

@ApiParam–给参数上加上解释

@RestController
@Api(tags ="User数据交互")
public class UserControoler
{
    //只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中
    @GetMapping("/User")
    @ApiOperation("展示用户")
    public String showUser(@ApiParam("特殊的名字") String u)
    {
        return u;
    }
}

我们可以简单测试一下，点击Try it out，然后点击Execute执行

---

常用注解总结

// @Api: 修饰整个类，描述Controller的作用
@Api(value = "注册登陆", tags = "注册登陆相关接口")
// @ApiOperation: 描述一个类的一个方法，或者说一个接口
@ApiOperation(value = "用户注册", notes = "用户注册", httpMethod = "POST")
@ApiParam			// 单个参数描述
// @ApiModel: 用对象来接收参数
@ApiModel(value = "用户对象BO", description = "用户从客户端传入的数据的封装")
// @ApiModelProperty: 用对象接收参数时，描述对象的一个字段
@ApiModelProperty(value = "用户名", name = "username", example = "Orcas", required = true)
@ApiResponse        // HTTP响应其中1个描述
@ApiResponses       // HTTP响应整体描述
@ApiIgnore		    // 使用该注解忽略这个API 
@ApiError 		    // 发生错误返回的信息
@ApiImplicitParam   // 一个请求参数
@ApiImplicitParams  // 多个请求参数
   =》 @ApiImplicitParams({
            @ApiImplicitParam(name = "page", value = "页码", required = true, paramType = "path", dataType = "int"),
            @ApiImplicitParam(name = "size", value = "每页记录数", required = true, paramType = "path", dataType = "int")})

@ApiImplicitParam属性

@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="Integer"       
        defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

---

总结: 发布的时候，记得关闭Swagger，可以通过生产环境设置来完成这一需求

---

swagger 3.0的swagger页面访问url

https://ip:port或域名/设置的请求前缀/swagger-ui/#/

---

参考文章

SpringBoot集成Swagger3.0

---

Swagger3增强插件----knife4j

<dependency>
    <groupId></groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

启动knife4j
在上面配置Swagger的Swagger3Config中添加@EnableKnife4j注解，该注解可以开启knife4j的增强功能。

@EnableKnife4j
@Configuration
@EnableOpenApi
public class Swagger3Config {
    // ...
}

此时，如果依旧访问http://localhost:8080/swagger-ui/会发现显示并没有变化。这里我们需要访问http://localhost:8088/。

整个项目源码地址：/secbr/springboot-all/tree/master/springboot-swagger3。

展示效果

此时启动项目，访问之后，你会发现现在文档风格变得非常酷炫。展示几个效果图来看看：

其中在“离线文档”一栏中可以看到四种形式的离线文档下载：Markdown、HTML、Word、OpenAPI。

其中个人感觉HTML格式的文档更具有没敢，也更方便查看，来一张图看看效果。

swagger3参考文档

---

Swagger3.0 异常：导致: For input string: ““

原因：

查看源码得知，源码中只判断了examole==null,忽略了""空字符串的情况!

解决方案：

 <!--指定swagger-models版本，解决报错-->
        <dependency>
            <groupId></groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.21</version>
        </dependency>
        
        <dependency>
            <groupId></groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.21</version>
        </dependency>

项目当前使用的swagger版本及UI版本

 <!--swagger-->
        <dependency>
            <groupId></groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

        <!-- swagger ui-->
        <dependency>
            <groupId></groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.2</version>
        </dependency>

        <!--指定swagger-models版本，解决报错-->
        <dependency>
            <groupId></groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.21</version>
        </dependency>

        <dependency>
            <groupId></groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.21</version>
        </dependency>