SpringBoot-使用Swagger文档

最新推荐文章于 2024-04-18 20:42:23 发布
最新推荐文章于 2024-04-18 20:42:23 发布
阅读量440 收藏 1
点赞数
分类专栏： Spring 文章标签： spring boot java spring
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/zZZ251682553/article/details/125143406
版权

前言

Swagger 是一套基于 OpenAPI 规范构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。

pom.xml文件

添加swagger2和swagger-ui依赖。

    <properties>
        <java.version>1.8</java.version>
        <swagger.version>2.9.2</swagger.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <!--swagger-ui-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>

        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <scope>runtime</scope>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
        </dependency>
    </dependencies>

配置文件

和整合jpa一样。

server:
  port: 8080
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/test?serverTimezone=GMT
    username: root
    password: 123456
    driver-class-name: com.mysql.jdbc.Driver
  jpa:
    properties:
      hibernate:
        hbm2ddl:
          auto: update
        dialect: org.hibernate.dialect.MySQL5InnoDBDialect
    show-sql: true

swagger2文档信息配置

文档信息配置，Swagger 还支持设置一些文档的版本号、联系人邮箱、网站、版权、开源协议等等信息，通过创建一个 ApiInfo 对象，并且使用 Docket.appInfo() 方法来设置。

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.huzh.springbootswagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("spring-boot-demo")
                .description("这是一个简单的 Swagger API 演示")
                .contact(new Contact("企鹅十五号", "https://yuexianhu.github.io", "*****@qq.com"))
                .version("1.0.0-SNAPSHOT")
                .build();
    }
}

实体类

实体描述，我们可以通过 @ApiModel 和 @ApiModelProperty 注解来对我们 API 中所涉及到的对象做描述。

@Entity
@ApiModel(description = "用户实体")
public class User {

    @ApiModelProperty(value = "主键id", hidden = true)
    @GeneratedValue
    @Id
    Integer id;

    @ApiModelProperty(value = "用户名称")
    @NotNull
    @Column
    private String username;

    @ApiModelProperty(value = "用户密码")
    @Column
    private String password;

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public User() {
    }

    public User(Integer id, @NotNull String username, String password) {
        this.id = id;
        this.username = username;
        this.password = password;
    }

    public User(@NotNull String username, String password) {
        this.username = username;
        this.password = password;
    }
}

repository类

public interface UserRepository extends JpaRepository<User, Integer> {
    User findById(int id);
}

Controller类

  1. 通过在控制器类上增加@Api 注解，可以给控制器增加描述和标签信息。
  2. 通过在接口方法上增加 @ApiOperation 注解来展开对接口的描述。
@RestController
@RequestMapping("/user")
@Api(tags = "用户操作接口", description = "提供用户相关的 Rest API")
public class UserController {
    @Autowired
    UserRepository userRepository;

    @ApiOperation(value = "获取用户详细信息", notes = "根据用户的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "query", dataType = "Integer")
    @GetMapping(value = "/findById")
    public User findById(@RequestParam(value = "id") int id) {
        User user = userRepository.findById(id);
        return user;
    }

    @ApiOperation(value = "获取用户列表", notes = "获取用户列表")
    @GetMapping(value = "/getUserList")
    public List getUserList() {
        return userRepository.findAll();
    }

    @ApiOperation(value = "保存用户", notes = "保存用户")
    @PostMapping(value = "/saveUser")
    public String saveUser(@RequestBody @ApiParam(name = "用户对象", value = "传入json格式", required = true) User user) {
        userRepository.save(user);
        return "success!";
    }

    @ApiOperation(value = "修改用户", notes = "修改用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "主键id", required = true, paramType = "query", dataType = "Integer"),
            @ApiImplicitParam(name = "username", value = "用户名称", required = true, paramType = "query", dataType = "String"),
            @ApiImplicitParam(name = "password", value = "用户密码", required = true, paramType = "query", dataType = "String")
    })
    @GetMapping(value = "/updateUser")
    public String updateUser(@RequestParam(value = "id") int id, @RequestParam(value = "username") String username,
                             @RequestParam(value = "password") String password) {
        User user = new User(id, username, password);
        userRepository.save(user);
        return "success!";
    }

    @ApiOperation(value = "删除用户", notes = "根据用户的id来删除用户")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "query", dataType = "Integer")
    @DeleteMapping(value = "/deleteUserById")
    public String deleteUserById(@RequestParam(value = "id") int id) {
        User user = userRepository.findById(id);
        userRepository.delete(user);
        return "success!";
    }
}

访问验证

image.png

高级配置

接口过滤

有些时候我们并不是希望所有的 Rest API 都呈现在文档上，这种情况下 Swagger2 提供给我们了两种方式配置，一种是基于 @ApiIgnore 注解，另一种是在 Docket 上增加筛选。

  1. @ApiIgnore 注解。
    如果想在文档中屏蔽掉删除用户的接口（user/delete），那么只需要在删除用户的方法上加上 @ApiIgnore 即可。
  2. 在 Docket 上增加筛选。
    Docket 类提供了 apis() 和 paths()两个方法来帮助我们在不同级别上过滤接口：
    apis()：这种方式我们可以通过指定包名的方式，让 Swagger 只去某些包下面扫描。
    paths()：这种方式可以通过筛选 API 的 url 来进行过滤。

自定义响应消息

Swagger 允许我们通过 Docket 的 globalResponseMessage() 方法全局覆盖 HTTP 方法的响应消息，但是首先我们得通过 Docket 的 useDefaultResponseMessages 方法告诉 Swagger 不使用默认的 HTTP 响应消息，假设我们现在需要覆盖所有 GET 方法的 500 和 403 错误的响应消息，我们只需要在 Swagger2Config.java 类中的 Docket Bean 下添加如下内容：

                .useDefaultResponseMessages(false)
                .globalResponseMessage(RequestMethod.GET, newArrayList(
                        new ResponseMessageBuilder()
                                .code(500)
                                .message("服务器发生异常")
                                .responseModel(new ModelRef("Error"))
                                .build(),
                        new ResponseMessageBuilder()
                                .code(403)
                                .message("资源不可用")
                                .build()
                ));

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-6bXGDstz-1654485569784)(https://raw.githubusercontent.com/YueXIanHu/blog-images/main/yuexianbolg/20220606111341.png)]

Swagger UI 的使用

接口查看

SwaggerUI 会以列表的方式展示所有扫描到的接口，初始状态是收缩的，我们只需要点击展开就好，而且会在左边标识接口的请求方式（GET、POST、PUT、DELETE 等等）。接口查看

接口调用

  • 点击接口展开后页面右上角的 Try it out 按钮。image.png
  • SwaggerUI 会给我们自动填充请求参数的数据结构，我们需要做的只是点击 Execute 即可发起调用。image.png

Model

SwaggerUI 会通过我们在实体上使用的 @ApiModel 注解以及@ApiModelProperty 注解来自动补充实体以及其属性的描述和备注。model

相关注解说明

Controller 相关注解

  • @Api: 可设置对控制器的描述。
注解属性类型描述
tagsString[]控制器标签。
descriptionString控制器描述（该字段被申明为过期）。

接口相关注解

  • @ApiOperation: 可设置对接口的描述。
注解属性类型描述
valueString接口说明。
notesString接口发布说明。
tagsStirng[]标签。
responseClass<?>接口返回类型。
httpMethodString接口请求方式。
  • @ApiIgnore: Swagger 文档不会显示拥有该注解的接口。
  • @ApiImplicitParams: 用于描述接口的非对象参数集。
  • @ApiImplicitParam: 用于描述接口的非对象参数，一般与 @ApiImplicitParams 组合使用。
注解属性描述
paramType查询参数类型，实际上就是参数放在那里。取值：
path：以地址的形式提交数据，根据 id 查询用户的接口就是这种形式传参。
query：Query string 的方式传参。
header：以流的形式提交。
form：以 Form 表单的形式提交。
dataType参数的数据类型。取值：
Long
String
name参数名字。
value参数意义的描述。
required是否必填。取值：
true：必填参数。
false：非必填参数。

Model 相关注解

  • @ApiModel: 可设置接口相关实体的描述。
  • @ApiModelProperty: 可设置实体属性的相关描述。
注解属性类型描述
valueString字段说明。
nameString重写字段名称。
dataTypeStirng重写字段类型。
requiredboolean是否必填。
exampleStirng举例说明。
hiddenboolean是否在文档中隐藏该字段。
allowEmptyValueboolean是否允许为空。
allowableValuesString该字段允许的值，当我们 API 的某个参数为枚举类型时，使用这个属性就可以清楚地告诉 API 使用者该参数所能允许传入的值。

参考文章

月弦YueXian
关注
  • 0
    点赞
  • 踩
  • 1
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
Spring Boot：整合Swagger文档
CHIKA2333的博客
07-30 176
spring-boot作为当前最为流行的Java web开发脚手架，越来越多的开发者选择用其来构建企业级的RESTFul API接口。这些接口不但会服务于传统的web端（b/s），也会服务于移动端。在实际开发过程中，这些接口还要提供给开发测试进行相关的白盒测试，那么势必存在如何在多人协作中共享和及时更新API开发接口文档的问题。假如你已经对传统的wiki文档共享方式所带来的弊端深恶痛绝，那么尝试一下Swagger2 方式，一定会让你有不一样的开发体验。
111-springboot-demo-swagger-v3-openapi.rar
03-07
从上述 Swagger 定义我们不难看出 Swagger 有以下 3 个重要的作用：将项目中所有的接口展现在页面上，这样后端程序员就不需要专门为前端使用者编写专门的接口文档；当接口更新之后，只需要修改代码中的 Swagger 描述...
swagger-ui-react：从swagger-ui生成swagger-ui-react的存储库
02-15
此回购的原因 此仓库表示swagger-ui-react的自定义版本，并为基础的swagger-ui构造函数添加了一些传递swagger-ui 。 我们需要使用swagger-ui-react （vs. swagger-ui ），因为它将React列为peerDependency ，这使得它可以很好地与React 16一起使用。直到合并到swagger-ui repo中， contour仓库才会继续使用此软件包。 一旦该PR合并，我就可以回到在轮廓的package.json使用原始的swagger-ui-react 。 由于swagger-ui-react是在swagger-ui的构建过程中生成的，因此我们需要swagger-ui-react构建swagger-ui-react ，并将其托管在与，以便在该仓库中引用Github URL。 package.json将正常工作（package
springboot整合swagger构建Api文档
07-24
springboot整合swagger构建Api文档，对于整理在线文档这是一大利器，相对于ssm整合是真的简单方便，不管是不是新手，一看就能懂，对于与前端交互，那是相当的便捷。
Swagger接口文档 —— 手把手教学，全方位超详细小白能看懂，百分百能用Java版
最新发布
dream_ready的博客
04-18 1250
使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，就可以做到生成接口文档，以及在线接口调试页面。官网：https://swagger.io/是为Java MVC框架集成Swagger生成Api文档的增强解决方案。
SpringBoot整合Swagger文档
a13131234的博客
08-21 295
SpringBoot整合Swagger文档springboot整合swagger步骤如下2.创建SwaggerConfig3. 输入地址我的是8080按自己的来 http://localhost:8080/swagger-ui.html#/ springboot整合swagger步骤如下 1.先导入jar包 <dependency> <groupId>io.springfox</groupId> <artif.
Springboot集成Swagger文档
AG.『Feng』的博客
08-07 477
springboot集成Swagger文档
springboot-swagger.zip--接口文档
03-18
狂神说java的swagger接口文档源代码
111-springboot-demo-swagger-v2.rar
03-07
SpringBoot接口 - 如何生成接口文档之Swagger技术栈准备知识点什么是OpenAPI规范（OAS)？什么是Swagger？Swagger和SpringFox有啥关系？什么是Knife4J? 和Swagger什么关系？实现案例之Swagger3POMSwagger Config...
111-springboot-demo-swagger-v2-bootstrap-ui.rar
03-07
从上述 Swagger 定义我们不难看出 Swagger 有以下 3 个重要的作用：将项目中所有的接口展现在页面上，这样后端程序员就不需要专门为前端使用者编写专门的接口文档；当接口更新之后，只需要修改代码中的 Swagger 描述...
springboot-09-swagger.zip
01-28
swagger是一款可以根据resutful风格生成的生成的接口开发文档，并且支持做测试的一款中间软件。 Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。 Swagger是一个规范和完整的框架,用于生成、描述、...
接口文档神器Swagger（上篇）
热门推荐
网易数帆社区博客
09-04 4万+
本文来自网易云社区作者：李哲接口文档管理一直是一个让人头疼的问题，伴随着各种接口文档管理平台涌现，如阿里开源的rap，ShowDoc，sosoapi，等等（网上能找到很多这种管理平台，包括我们自己做的idoc）。这些平台都是一个共同特点，创建文档，编辑，保存文档，一些功能强大的还有mock，统计接口信息等功能，所以这些平台更像一个接口文档的存储管理系统，可以方便人们查看、编辑文档。然而接口一般都是...
springboot整合swagger接口文档
2301_77664771的博客
06-26 499
（简称 MP）是一个的增强工具，在 MyBatis 的基础上只做增强不做改变，为简化开发、提高效率而生。愿景我们的愿景是成为 MyBatis 最好的搭档，就像魂斗罗中的 1P、2P，基友搭配，效率翻倍。特点：无侵入：只做增强不做改变，引入它不会对现有工程产生影响，如丝般顺滑损耗小：启动即会自动注入基本 CURD，性能基本无损耗，直接面向对象操作强大的 CRUD 操作：内置通用 Mapper、通用 Service，仅仅通过少量配置即可实现==单表大部分 CRUD 操作。
SpringBoot（五）：Swagger接口文档
千里之行，始于足下
03-23 280
Swagger 是一个用于解决接口文档问题的框架，主要是通过一些 Swagger 提供的注解，为开发者自动生成相应的接口文档，让开发者从接口文档的编写工作中解放出来。
SpringBoot整合swagger接口文档
z18222043061的博客
08-13 216
SpringBoot整合swagger SpringBoot整合swagger的步骤很简单，一共分为四步即可 1.pom.xml配置 将以下代码放到pom.xml的《dependencies》标签下并从新运行maven <!--swagger配置--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-
SpringBoot整合Swagger接口文档
weixin_54065960的博客
06-19 116
springboot整合swagger接口文档使用
springboot 整合整合Swagger文档
wwwzhouzy的专栏
08-22 254
一、简介 spring-boot作为当前最为流行的Java web开发脚手架，越来越多的开发者选择用其来构建企业级的RESTFul API接口。这些接口不但会服务于传统的web端（b/s），也会服务于移动端。在实际开发过程中，这些接口还要提供给开发测试进行相关的白盒测试，那么势必存在如何在多人协作中共享和及时更新API开发接口文档的问题。 假如你已经对传统的wiki文档共享方式所带来的弊端深恶痛绝，那么尝试一下Swagger2 方式，一定会让你有不一样的开发体验。 使用 Swagger 集成文档具有.
SpringBoot利用Swagger2构建Api文档
kenyon的博客
02-09 262
现在越来越多的项目使用前后端分离，在开发中我们构建RESTful风格Api时候需要提供对应的接口文档，这个工作量也是想当的惊人的，有时候写几个接口文档可能就需要一天的时间。 我们可以利用SpringBoot整合Swagger2来帮我们快速实现接口文档，它可以根据我们写的注释来实现自动生成接口文档。 整合Swagger2 引入依赖<dependency> <groupId...
springboot项目整合swagger文档
05-20
Spring Boot 项目可以很方便地整合 Swagger 文档，只需要按照以下步骤进行操作即可。 1. 在 `pom.xml` 文件中添加 Swagger 的依赖： ```xml <groupId>io.springfox <artifactId>springfox-swagger2 ${...

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值