SpringBoot整合Swagger2

最新推荐文章于 2023-08-11 14:24:06 发布

Super周博客

最新推荐文章于 2023-08-11 14:24:06 发布

阅读量168

点赞数 4

分类专栏： SpringBoot学习文章标签： swagger2

本文链接：https://blog.csdn.net/qq_33922980/article/details/91351756

版权

SpringBoot学习专栏收录该内容

20 篇文章 0 订阅

订阅专栏

1.什么是Swagger2，它能够做什么？

swagger是一个流行的API开发框架，这个框架以“开放API声明”（OpenAPI Specification，OAS）为基础，
对整个API的开发周期都提供了相应的解决方案，是一个非常庞大的项目（包括设计、编码和测试，几乎支持所有语言）。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。
文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

springfox大致原理:

springfox的大致原理就是，在项目启动的过种中，spring上下文在初始化的过程，
框架自动跟据配置加载一些swagger相关的bean到当前的上下文中，并自动扫描系统中可能需要生成api文档那些类，
并生成相应的信息缓存起来。如果项目MVC控制层用的是springMvc那么会自动扫描所有Controller类，并生成对应的文档描述数据.

该数据是json格式，通过路径：项目地址/ v2/api-docs可以访问到该数据，然后swaggerUI根据这份数据生成相应的文档描述界面。
因为我们能拿到这份数据，所以我们也可以生成自己的页面.

2.SpringBoot集成Swagger2

1.添加有关的依赖，一个是整个swagger2的依赖，另一个是展示页面ui的依赖

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

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

3.添加Swagger2有关的配置文件

/**
 * @ Author     ：Zgq
 * @ Date       ：Created in 11:20 2019/6/9
 * @ Description：配置Swagger2 现在Swagger2还不能为我们生成API文档,因为我们还没有对它进行配置.
 * @ Modified By：
 * @Version: $
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig{

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //选择你需要扫描的有api的controller类所在的包
                .apis(RequestHandlerSelectors.basePackage("com.example.echart.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful API")
                .description("rest api 文档构建利器")
                .termsOfServiceUrl("https://blog.csdn.net/qq_33922980/article/details/91351756")
                .contact("itguang")
                .version("1.0")
                .build();
    }

}

4.有关Swagger2的常用注解

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数，描述整个对象的信息
@ApiProperty：用对象接收参数时，描述对象的一个属性
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数描述
@ApiImplicitParams：多个请求参数描述