【SpringBoot】Spring Boot 集成SwaggerAPI

Spring Boot 集成SwaggerAPI

文章目录

• Spring Boot 集成SwaggerAPI
• Swagger
• 添加依赖
• 配置类 config
• 控制类 controller
• 接口测试
• 页面测试
• 常用注解
• 资料参考

学习Spring Boot框架使用Swagger构建RESTful API。

简单记录 - Spring Boot+Spring Cloud+Vue+Element项目实战

Spring Boot作为当前最为流行的Java Web开发脚手架，越来越多的开发者选择用其来构建企业级的RESTFul API接口。

使用Swagger集成文档具有以下几个优势：

功能丰富：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能。

及时更新：开发过程中花一点写注释的时间，就可以及时地更新API文档，省心省力。

整合简单：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。

官方网站：https://swagger.io/

官方文档：https://swagger.io/docs/

Swagger

那什么是Swagger呢？

Swagger（官网地址：https://swagger.io/）

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

API Developmentfor Everyone

Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset. Find out how Swagger can help you design and document your APIs at scale.

在Spring Boot中如何使用呢？？？

在Spring Boot项目中使用Swagger其实很简单，大致分为以下三步

（1）加入Swagger依赖。

（2）加入Swagger文档配置。

（3）使用Swagger注解编写API文档和API实体模板。

创建一个Spring Boot项目 school

添加依赖

在pom文件内添加Maven依赖，这里选择2.9.2版本。

pom.xml

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

添加数据源配置

在src/main/resources下，创建application.yml文件，添加8080端口。

server:
          port: 8080

配置类 config

新建config包，并在其下添加Swagger配置类。

SwaggerConfig.java

package com.awen.school.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger配置
 * @author liu Awen
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
        		.apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder().build();
    }

}

控制类 controller

新建controller包，并在其下添加HelloController控制类，添加一个hello接口，

HelloController.java

package com.awen.school.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping(value="/hello")
    public Object hello() {
        return "Hello School Applications!";
    }

}

接口测试

启动应用，在浏览器中访问http://localhost:8080/hello,可以看到服务已经调用成功了。

页面测试

在浏览器中访问http://localhost:8080/swagger-ui.html#/，我们就可以看到Swagger的接口文档页面了，还可以选择接口进行测试，如图所示。

单击展开hello接口，单击右侧的try it out→execute，

发现接口成功返回“Hello School Applications!”信息，如图所示。

可以通过Swagger来测试接口了。

常用注解

swagger 通过注解接口生成文档，包括接口名，请求方法，参数，返回信息等

@Api: 修饰整个类，用于controller类上

@ApiOperation: 描述一个接口，用户controller方法上

@ApiParam: 单个参数描述

@ApiModel: 用来对象接收参数,即返回对象

@ApiModelProperty: 对象接收参数时，描述对象的字段

@ApiResponse: Http响应其中的描述，在ApiResonse中

@ApiResponses: Http响应所有的描述，用在

@ApiIgnore: 忽略这个API

@ApiError: 发生错误的返回信息

@ApiImplicitParam: 一个请求参数

@ApiImplicitParam: 多个请求参数

更多说明参考 Swagger 使用手册

资料参考

（1）： Spring Boot+Spring Cloud+Vue+Element项目实战：手把手教你开发权限管理系统/徐丽健著.—北京：清华大学出版社，2019

（2）：Spring Boot + Spring Cloud 实现权限管理系统 后端篇（六）：集成 Swagger API

（3）：Spring实战（第5版）作者：[美]克雷格·沃斯译者：张卫滨出版社：人民邮电出版社出版时间：2020-02

（4）：Spring Boot 2实战之旅／杨洋著．—北京：清华大学出版社，2019