系列学习 Swagger 之第 1 篇 —— 认识 Swagger，Swagger 简单入门

2023-11-17 18:03:01

为了方便查阅，直接放 Swagger 的接口地址（可以忽略这句话）

http://127.0.0.1/swagger-ui.html#/user-controller

你们所在的公司接口文档是用什么写的？

相信无论是前端还是后台，或多或少地被接口文档折磨过。前端经常抱怨后台给的接口文档与实际情况不一致，后端觉得写接口文档浪费时间，经常来不及更新。前后端的矛盾有时就是这样产生的。很多公司接口文档还是用 World 文档或者 Excel 写的！随着时间推移和项目的迭代，线下的接口文档往往很容易就跟不上了。

这里推荐本人之前用过的在线文档 doclever：http://doclever.cn/ 说明书：http://doclever.cn/controller/read/read.html#5a532f98b7731a2ba86093b3

DOClever专为中小型团队量身打造，旨在解决接口的管理，测试与数据生成，实现真正的一体化解决方案。

我们来讲解 Swagger。

官网：https://swagger.io/

理论参考：https://www.jianshu.com/p/349e130e40d5

Swagger 常用注解使用详解：https://blog.csdn.net/wyb880501/article/details/79576784

Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

Swagger Inspector: 感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。

Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

开始搭建 Swagger 环境

我们使用 Swagger 2.10.5 版本，注解已经不支持 @EnableSwagger2 了，修改为以下两种，请选择一种：@EnableSwagger2WebMvc 或者 @EnableSwagger2WebFlux

查看 swagger 最新版本地址：https://mvnrepository.com/artifact/io.springfox/springfox-swagger2，建议收藏 maven 地址，可以查看很多开源产品的最新版本。

maven 依赖有 3 个，完整代码如下：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.study</groupId>
    <artifactId>study-swagger</artifactId>
    <version>1.0-SNAPSHOT</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.2.RELEASE</version>
    </parent>

    <properties>
        <!-- 配置 Swagger 版本 -->
        <swagger.version>2.10.5</swagger.version>
    </properties>

    <dependencies>
        <!--Spring boot 集成包-->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
        </dependency>
        <!-- SpringBoot整合Web组件 -->
        <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>
        <!-- lombok 依赖 -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>

        <!-- SpringBoot swagger2 接口 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <!-- SpringBoot swagger2 UI -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <!-- SpringBoot swagger2 WebMVC -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-spring-webmvc</artifactId>
            <version>${swagger.version}</version>
        </dependency>
    </dependencies>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>Hoxton.SR2</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
</project>

Swagger 配置类：

package com.study.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.EnableSwagger2WebMvc;

/**
 * @author biandan
 * @description SwaggerConfig的相关配置
 * @signature 让天下没有难写的代码
 * @create 2021-06-06 下午 9:42
 */
@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(myApiInfo()) //文档信息
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.study.controller")) //扫描的包
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建文档信息
     * @return
     */
    private ApiInfo myApiInfo(){
        return new ApiInfoBuilder()
                .title("流放深圳 Swagger 接口演示") //文档标题
                .description("这是我的第一个 Swagger API 接口文档") //文档描述
                .termsOfServiceUrl("http://www.baidu.com") //服务条款地址
                .version("V1.0") //版本号
                .build();
    }
}

实体类：如果不懂 lombok 表达式的用法，可以查看我的博客：https://blog.csdn.net/BiandanLoveyou/article/details/117632905

package com.study.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.*;

/**
 * @author biandan
 * @description
 * @signature 让天下没有难写的代码
 * @create 2021-06-06 下午 5:45
 */
@Data
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor(staticName = "of")
@Builder
@ApiModel(description = "返回的用户实体信息类")
public class UserEntity {

    @ApiModelProperty(value = "用户ID")
    private Integer id;

    @ApiModelProperty(value = "用户姓名")
    private String userName;

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

    @ApiModelProperty(value = "描述")
    private String desc;

}

说明：

@ApiModel：用于响应类上，表示一个返回响应数据的信息
@ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性

说一句：测试成功后，可以在返回信息上点击【Model】，就可以看到了。

Controller 类：

package com.study.controller;

import com.study.entity.UserEntity;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author biandan
 * @description
 * @signature 让天下没有难写的代码
 * @create 2021-06-06 下午 5:45
 */
@RestController
@Api(tags = "用户信息管理")
@RequestMapping("/api")
public class UserController {

    @PostMapping("/getUserInfo")
    @ApiOperation(value = "查询用户信息接口", notes = "这是一段方法的描述")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userId", value = "用户Id", required = false, dataType = "String"),
            @ApiImplicitParam(name = "userName", value = "用户名称", required = true, dataType = "String")
    })
    public UserEntity getInfo(@RequestParam(value = "userId",required = false) Integer userId,
                              @RequestParam("userName") String userName) {
        System.out.println("userName=" + userName);
        System.out.println("userId=" + userId);
        UserEntity userEntity = new UserEntity();
        userEntity.setId(userId);
        userEntity.setUserName(userName);
        userEntity.setPassword("123456");
        userEntity.setDesc("让天下没有难写的代码");
        return userEntity;
    }
}

说明：

1、@Api：用在请求的类上，表示对类的说明。tags="说明该类的作用，可以在UI界面上看到的注解，如下图"

2、@ApiOperation：用在请求的方法上，说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"

3、@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传，true、false
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，如果是整数，请使用 int，而不是 Integer 。
defaultValue：参数的默认值

4、如果只有一个参数需要说明，使用 @ApiImplicitParam(name = "userId", value = "用户Id", required = false, dataType = "String") 即可。如果有多个，则使用 @ApiImplicitParams

application.yml 配置信息：

server:
  port: 80

# 将SpringBoot项目作为单实例部署调试时，不需要注册到注册中心
eureka:
  client:
    fetch-registry: false
    register-with-eureka: false

spring:
  application:
    name: swagger-server

启动类：

package com.study;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * @author biandan
 * @description
 * @signature 让天下没有难写的代码
 * @create 2021-06-06 下午 5:44
 */
@SpringBootApplication
public class SwaggerApplication {

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

启动微服务，浏览器地址输入：http://127.0.0.1/swagger-ui.html#/user-controller 注意后面的 URL 参数 /swagger-ui.html#/user-controller 是固定的。

swagger 也可以测试，右上角 try it out

输入参数，点击 execute

对返回的结果还可以下载，默认 json 格式。

OK，swagger 正式入门！

本篇博客代码：https://pan.baidu.com/s/1_9v4hwj3htFqJe0W7JjxMQ 提取码：qeg7

码农公寓

为了方便查阅，直接放 Swagger 的接口地址（可以忽略这句话）

你们所在的公司接口文档是用什么写的？

开始搭建 Swagger 环境

相关文章