Spring Boot集成Swagger简易教程

简介: Swaggerswagger  Swagger号称是史上最流行的、最好用的API接口文档构建工具,它支持多种语言包括Java在内,本文仅关注如何使用Spring Boot来集成Swagger,更多关于Swagger的介绍可以查看以下几个链接。

Swagger

img_4bca3c68e7a3b4ebd1fc461026b05b99.png
swagger

  Swagger号称是史上最流行的、最好用的API接口文档构建工具,它支持多种语言包括Java在内,本文仅关注如何使用Spring Boot来集成Swagger,更多关于Swagger的介绍可以查看以下几个链接。

Swagger - 官网
Swagger - Github

SpringFox

  SpringFox最初叫Swagger-SpringMVC,从字面意义上简单来理解是使用了SpringMVC来集成Swagger,后来演变成SpringFox这么一个项目(或组织),SpringFox官网有这么一句:Automated JSON API documentation for API's built with Spring(针对Spring构建的API的自动化JSON API文档)。好了,下来我们只需用SpringFox提供的三方库来快速集成一下Spring Boot和Swagger。

SpringFox
SpringFox - Documentation

1. 添加Maven依赖

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

2. 开启Swagger

  在Spring Boot启动类上添加@EnableSwagger2即可。

@SpringBootApplication
@EnableSwagger2 //开启Swagger
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

3. 配置Swagger

  

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 这里是全局扫描有@Api注解得类,还可以扫描任意位置,指定包以及针对方法上的指定注解
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) 
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Title")
                .description("Description")
                .termsOfServiceUrl("")
                .contact(new Contact("", "", ""))
                .license("")
                .licenseUrl("")
                .version(" xxx ")
                .build();
    }

}

4. 运行效果

  启动Spring Boot后,可以点击查看(更改为你的本地地址) http://localhost:8080/swagger-ui.html#/ ,效果如下:

img_eba33277840c962d9af125a7669d9791.png
swagger-ui

5. 常用注解

  Swagger的所有注解定义在io.swagger.annotations包下,下面列一些经常用到的,未列举出来的可以另行查阅说明:

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

6. 使用Swagger

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

img_20d2a0fa544303373351a952c0f0bfd8.png
swagger-test

End

  Swagger是个优秀的工具,现在国内已经有很多的中小型互联网公司都在使用它,相较于传统的要先出Word接口文档再测试的方式,显然这样也更符合现在的快速迭代开发行情。当然了,提醒下大家在正式环境要记得关闭Swagger,一来出于安全考虑二来也可以节省运存。之前看到过一篇深入Swagger原理的文章,最后分享出来给大家:API管理工具Swagger介绍及Springfox原理分析

目录
相关文章
|
3天前
|
druid Java 关系型数据库
Spring Boot2 系列教程(二十五)Spring Boot 整合 Jpa 多数据源
Spring Boot2 系列教程(二十五)Spring Boot 整合 Jpa 多数据源
14 0
|
4天前
|
前端开发 安全 JavaScript
Spring Boot2 系列教程(十四)CORS 解决跨域问题
Spring Boot2 系列教程(十四)CORS 解决跨域问题
13 0
|
4天前
|
安全 算法 Java
在Spring Boot项目中集成Jasypt(Java Simplified Encryption)
在Spring Boot项目中集成Jasypt(Java Simplified Encryption)
20 7
|
4天前
|
消息中间件 Java Kafka
集成Kafka到Spring Boot项目中的步骤和配置
集成Kafka到Spring Boot项目中的步骤和配置
25 7
|
4天前
|
监控 NoSQL Java
在Spring Boot中集成Redisson实现延迟队列
在Spring Boot中集成Redisson实现延迟队列
28 6
|
4天前
|
druid Java 关系型数据库
在Spring Boot中集成Druid实现多数据源有两种常用的方式:使用Spring Boot的自动配置和手动配置。
在Spring Boot中集成Druid实现多数据源有两种常用的方式:使用Spring Boot的自动配置和手动配置。
29 5
|
4天前
|
Java 数据库连接 mybatis
在Spring Boot应用中集成MyBatis与MyBatis-Plus
在Spring Boot应用中集成MyBatis与MyBatis-Plus
29 5
|
4天前
|
前端开发 Java 程序员
Spring Boot (十五): 优雅的使用 API 文档工具 Swagger2
Spring Boot (十五): 优雅的使用 API 文档工具 Swagger2
13 1
|
3天前
|
Java 数据库连接 数据库
Spring Boot集成MyBatis Plus
Spring Boot集成MyBatis Plus
11 0
|
4天前
|
NoSQL Java Redis
Spring Boot2 系列教程(二十六)Spring Boot 整合 Redis
Spring Boot2 系列教程(二十六)Spring Boot 整合 Redis
10 0