不用在写这么多的接口文档-SpringBoot整合Swagger，解放你打接口文档的双手

最新推荐文章于 2024-10-16 11:02:39 发布

卑微小彭

最新推荐文章于 2024-10-16 11:02:39 发布

阅读量239

点赞数

分类专栏： Swagger SpringBoot 文章标签： spring boot java

本文链接：https://blog.csdn.net/Systemoutprintl/article/details/108160719

版权

SpringBoot 同时被 2 个专栏收录

3 篇文章 0 订阅

订阅专栏

Swagger

1 篇文章 0 订阅

订阅专栏

今天学习了一下Swagger的继承文档功能

我们为什么要使用Swagger呢？

在前后端通过分离的方式开发项目时，我们作为后端程序员，需要给予前端各种各样的接口，但是前端是不懂得代码的，所以我们在进行接口开发之后，还需要为接口写入一个文档，单独为接口介绍，使得前端人员能够通过此介绍方式在前端页面能够调用我们后台的控制器，而有时候在开发时，因为某些因素的变化，我们就需要对接口进行改变，那时，我们又需要重新修改接口并且还要重写我们给与前端的接口介绍文档，这样就使得我们的开发变得十分的麻烦，因此，Swagger框架就为此功能而生成了。

在使用Swagger的之前，我们首先使用手写的接口介绍尝试一次

--------------------------------------------------------------------------

接口：用户登录

接口路径：localhost:9999/dologin

请求参数:userName,password

参数名称	参数类型	注释
userName	String	用户名
password	String	密码

请求方式：post

返回的数据结构

1 或者 2

1表示登录成功在数据库中有数据

2表示登录失败在数据库中没有数据

参数说明:

参数名称	参数类型	注释
Integer	Integer	返回1表示登录成功 2表示登录失败

接口：删除用户

接口路径：localhost:9999/removeUser

请求参数：id

参数名称	参数类型	注释
id	Integer	用户的id编号

请求方式：get

返回的数据结构：

Integer

1或者0

参数说明

返回参数名称	参数类型	注释
Integer数据	Integer	返回1表示删除成功

接口：查询学生

接口路径：localhost:9004/student

请求参数：无

请求方式：get

返回的数据结构：

[
  {
    "studentNo": 1,
    "studentName": "张三",
    "studentAge": 18,
    "studentSex": "男"
  },
  {
    "studentNo": 2,
    "studentName": "小花",
    "studentAge": 17,
    "studentSex": "女"
  },
  {
    "studentNo": 3,
    "studentName": "小鲸鱼",
    "studentAge": 10,
    "studentSex": "女"
  },
  {
    "studentNo": 4,
    "studentName": "大鲨鱼",
    "studentAge": 16,
    "studentSex": "男"
  },
  {
    "studentNo": 5,
    "studentName": "大脑虎",
    "studentAge": 20,
    "studentSex": "男"
  }
]

参数说明

参数名称	参数类型	注释
studentNo	Integer	学生编号
studentName	String	姓名
studentAge	String	年龄
studentSex	String	性别

接口：返回一个map集合

接口路径：localhost:9004/map

请求参数：无

请求方式：get

返回的数据结构：

{
"其一":“劝君莫惜金缕衣，劝君须惜少年时。有花堪折直须折，莫待无花空折枝。”,
"金缕衣":“杜秋娘”,
"其二":"青天无云月如烛，露泣梨花白如玉。子规一夜啼到明，美人独在空房宿。"
}

参数说明

返回参数名称	参数类型	注释
map的key值	String	返回map集合的key值
map的value值	String	返回map集合的value值

---------------------------------------------------------------------------

本次我写入了四个接口介绍感觉十分的麻烦，并且在写的过程中也遇到过代码不小心错误的问题。而这些问题如果是放到上百个接口以上的项目时，就容易极大的增加我们的工作量，这时，Swagger的好处就体现出来了。

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

功能丰富：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；
及时更新：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；
整合简单：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。

使用Swagger：

1.添加他的相关依赖

WEB依赖

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

swagger依赖，这里选择 2.9.2 版本。

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

添加配置类

添加一个swagger 配置类，在工程下新建 config 包并添加一个 SwaggerConfig 配置类。

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;

@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()
                .title("Kitty API Doc")
                .description("This is a restful api document of Kitty.")
                .version("1.0")
                .build();
    }

}

在添加完配置文件后，即代表Swagger已经配置成功了，我们接下来就

添加一个控制器测试一下Swagger

添加一个控制器，在工程下新建 controller包并添加一个 HelloController控制器。

HelloController.java

package com.louis.springboot.demo.controller;

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

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

/* 类注解 */
@Api(value = "desc of class")
@RestController
public class HelloController {

    /* 方法注解 */
    @ApiOperation(value = "desc of method", notes = "")
    @GetMapping(value="/hello")
    public Object hello( /* 参数注解 */ @ApiParam(value = "desc of param" , required=true ) @RequestParam String name) {
        return "Hello " + name + "!";
    }
}