博客
关于我
强烈建议你试试无所不能的chatGPT,快点击我
Springboot整合Swagger2.0、3.0
阅读量:580 次
发布时间:2019-03-11

本文共 6138 字,大约阅读时间需要 20 分钟。

目录

 


一、Swagger2.0

在团队开发中,一个好的 API 文档不但可以减少大量的沟通成本,还可以帮助一位新人快速上手业务。传统的做法是由开发人员创建一份 RESTful API 文档来记录所有的接口细节,并在程序员之间代代相传。

这种做法存在以下几个问题:

  • API 接口众多,细节复杂,需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等,想要高质量的完成这份文档需要耗费大量的精力;

  • 难以维护。随着需求的变更和项目的优化、推进,接口的细节在不断地演变,接口描述文档也需要同步修订,可是文档和代码处于两个不同的媒介,除非有严格的管理机制,否则很容易出现文档、接口不一致的情况

Swagger2 的出现就是为了从根本上解决上述问题。它作为一个规范和完整的框架,可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务:

  1. 接口文档在线自动生成,文档随接口变动实时更新,节省维护成本

  2. 支持在线接口测试,不依赖第三方工具

依赖

...
io.springfox
springfox-swagger-ui
2.9.2
io.springfox
springfox-swagger2
2.9.2

Swagger2 配置

Swagger2 的配置也是比较容易的,在项目创建成功之后,只需要开发者自己提供一个 Docket 的 Bean 即可,如下:

@Configuration@EnableSwagger2public class SwaggerConfig {    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .pathMapping("/")                .select()                .apis(RequestHandlerSelectors.basePackage("org.javaboy.controller"))                .paths(PathSelectors.any())                .build().apiInfo(new ApiInfoBuilder()                        .title("SpringBoot整合Swagger")                        .description("SpringBoot整合Swagger,详细信息......")                        .version("9.0")                        .contact(new Contact("test","blog.csdn.net","test@gmail.com"))                        .license("The Apache License")                        .licenseUrl("http://www.test.org")                        .build());    }}

这里提供一个配置类,首先通过 @EnableSwagger2 注解启用 Swagger2 ,然后配置一个 Docket Bean,这个 Bean 中,配置映射路径和要扫描的接口的位置,在 apiInfo 中,主要配置一下 Swagger2 文档网站的信息,例如网站的 title,网站的描述,联系人的信息,使用的协议等等。

如此,Swagger2 就算配置成功了,非常方便。

此时启动项目,输入 http://localhost:8080/swagger-ui.html,能够看到如下页面,说明已经配置成功了:

创建接口

接下来就是创建接口了

@RestController@Api(tags = "用户管理相关接口")@RequestMapping("/user")public class UserController {    @PostMapping("/")    @ApiOperation("添加用户的接口")    @ApiImplicitParams({            @ApiImplicitParam(name = "username", value = "用户名", defaultValue = "李四"),            @ApiImplicitParam(name = "address", value = "用户地址", defaultValue = "深圳", required = true)    })    public RespBean addUser(String username, @RequestParam(required = true) String address) {        return new RespBean();    }    @GetMapping("/")    @ApiOperation("根据id查询用户的接口")    @ApiImplicitParam(name = "id", value = "用户id", defaultValue = "99", required = true)    public User getUserById(@PathVariable Integer id) {        User user = new User();        user.setId(id);        return user;    }    @PutMapping("/{id}")    @ApiOperation("根据id更新用户的接口")    public User updateUserById(@RequestBody User user) {        return user;    }}

注解说明:

@Api 注解可以用来标记当前 Controller 的功能。

@ApiOperation 注解用来标记一个方法的作用。
@ApiImplicitParam 注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入。
如果有多个参数,则需要使用多个 @ApiImplicitParam 注解来描述,多个 @ApiImplicitParam 注解需要放在一个 @ApiImplicitParams 注解中。
需要注意的是,@ApiImplicitParam 注解中虽然可以指定参数是必填的,但是却不能代替 @RequestParam(required = true) ,前者的必填只是在 Swagger2 框架内必填,抛弃了 Swagger2 ,这个限制就没用了,所以假如开发者需要指定一个参数必填, @RequestParam(required = true) 注解还是不能省略。
如果参数是一个对象(例如上文的更新接口),对于参数的描述也可以放在实体类中。例如下面一段代码:
 

@ApiModelpublic class User {    @ApiModelProperty(value = "用户id")    private Integer id;    @ApiModelProperty(value = "用户名")    private String username;    @ApiModelProperty(value = "用户地址")    private String address;    //getter/setter}

刷新刚刚打开的页面,可以看到如下效果:

可以看到,所有的接口这里都列出来了,包括接口请求方式,接口地址以及接口的名字等

二、Swagger3.0

依赖

这两个,一个用来生成接口文档(JSON 数据),另一个用来展示将 JSON 可视化。

io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2

在 3.0 版本中,我们不需要这么麻烦了,一个 starter 就可以搞定:

io.springfox
springfox-boot-starter
3.0.0

和 Spring Boot 中的其他 starter 一样,springfox-boot-starter 依赖可以实现零配置以及自动配置支持。也就是说,如果你没有其他特殊需求,加一个这个依赖就行了,接口文档就自动生成了。

支持 OpenAPI

什么是 OpenAPI?

OpenAPI 规范其实就是以前的 Swagger 规范,它是一种 REST API 的描述格式,通过既定的规范来描述文档接口,它是业界真正的 API 文档标准,可以通过 YAML 或者 JSON 来描述。它包括如下内容:

  • 接口(/users)和每个接口的操作(GET /users,POST /users)
  • 输入参数和响应内容
  • 认证方法
  • 一些必要的联系信息、license 等。

关于 OpenAPI 的更多内容,感兴趣的小伙伴可以在 GitHub 上查看:

接口地址

3.0 中的接口地址也和之前有所不同,以前在 2.9.2 中我们主要访问两个地址:

  • 文档接口地址:
  • 文档页面地址:

现在在 3.0 中,这两个地址也发生了变化:

  • 文档接口地址:
  • 文档页面地址:

特别是文档页面地址,如果用了 3.0,而去访问之前的页面,会报 404。

注解

旧的注解还可以继续使用,不过在 3.0 中还提供了一些其他注解。

例如我们可以使用 @EnableOpenApi 代替以前旧版本中的 @EnableSwagger2。

但是实际使用中,@EnableOpenApi 注解的功能不明显,加不加都行。翻了下源码,@EnableOpenApi 注解主要功能是为了导入 OpenApiDocumentationConfiguration 配置类,如下:

123456
@Retention(value = java.lang.annotation.RetentionPolicy.RUNTIME)@Target(value = {java.lang.annotation.ElementType.TYPE})@Documented@Import(OpenApiDocumentationConfiguration.class)public @interface EnableOpenApi {}

自动化配置类 OpenApiAutoConfiguration,如下:

12345678910111213141516
@Configuration@EnableConfigurationProperties(SpringfoxConfigurationProperties.class)@ConditionalOnProperty(value = "springfox.documentation.enabled", havingValue = "true", matchIfMissing = true)@Import({    OpenApiDocumentationConfiguration.class,    SpringDataRestConfiguration.class,    BeanValidatorPluginsConfiguration.class,    Swagger2DocumentationConfiguration.class,    SwaggerUiWebFluxConfiguration.class,    SwaggerUiWebMvcConfiguration.class})@AutoConfigureAfter({ WebMvcAutoConfiguration.class, JacksonAutoConfiguration.class,    HttpMessageConvertersAutoConfiguration.class, RepositoryRestMvcAutoConfiguration.class })public class OpenApiAutoConfiguration {}

可以看到,自动化配置类里边也导入了 OpenApiDocumentationConfiguration。

所以在正常情况下,实际上不需要添加 @EnableOpenApi 注解。

根据 OpenApiAutoConfiguration 上的 @ConditionalOnProperty 条件注解中的定义,我们发现,如果在 application.properties 中设置 springfox.documentation.enabled=false,即关闭了 swagger 功能,此时自动化配置类就不执行了,这个时候可以通过 @EnableOpenApi 注解导入 OpenApiDocumentationConfiguration 配置类。技术上来说逻辑是这样,不过应用中暂未发现这样的需求(即在 application.properties 中关闭 swagger,再通过 @EnableOpenApi 注解开启)。

另外,以前我们用的 @ApiResponses/@ApiResponse 注解,在 3.0 中名字没变,但是所在的包变

另外,我们之前用的 @ApiOperation 注解在 3.0 中可以使用 @Operation 代替。

另外还有一些新注解如 @Parameter、Parameters、@Schema 等

 

参考地址:

你可能感兴趣的文章