Swagger的使用（第一个案例）

朱雀 2021-09-25 02:04 320阅读 0赞

> **大家好，我是邵奈一，一个不务正业的程序猿、正儿八经的斜杠青年。**  
> 1、世人称我为：被代码耽误的诗人、没天赋的书法家、五音不全的歌手、专业跑龙套演员、不合格的运动员…  
> 2、这几年，我整理了很多IT技术相关的教程给大家，爱生活、爱分享。  
> 3、如果您觉得文章有用，请收藏，转发，评论，并关注我，谢谢！  
> **博客导航跳转（请收藏）：**[邵奈一的技术博客导航][Link 1]  
> | [公众号][Link 2] | [微信][Link 3] | [微博][Link 4] | [CSDN][] | [简书][Link 5] |

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

### 教程目录 ###

*  0x00 教程内容
 *  0x01 配置Swagger
 *   *   *   *   *  1. 添加 Swagger 依赖
                 *  2. 配置 Swagger
 *  0x02 检验Swagger
 *   *   *   *   *  1. 启动项目
 *  0x03 第一个例子
 *   *   *   *   *  1. 添加注解
                 *  2. 查看结果
 *  0xFF 总结

# 0x00 教程内容 #

# 0x01 配置Swagger #

##### 1. 添加 Swagger 依赖 #####

（1）在`pom.xml`文件中导入 `swagger` 依赖：

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

##### 2. 配置 Swagger #####

（1）新建一个`Swagger2Config` ，添加上相关的配置

package com.example.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;
    
    /** * @Auther: shaonaiyi@163.com * @Date: 2021/1/6 11:51 * @Description: Swagger2配置类 */
    @Configuration
    @EnableSwagger2
    public class Swagger2Config { 
        @Bean
        public Docket createRestApi() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("邵奈一-Swagger教学")
                    .description("邵奈一-Swagger教学-Restful API")
                    .termsOfServiceUrl("http://127.0.0.1:8080/")
                    .contact("邵奈一")
                    .version("1.0")
                    .build();
        }
    
    }

（2）代码解释：  
主要包含了两个方法，`createRestApi()`和`apiInfo()`，而后者返回的内容实际是个前者使用的。

**1、createRestApi()**  
返回的是 `Docket` 类型，是固定的写法，大家不用关心。在方法内部，使用匿名内部类的方式实例化了一个 Docket 对象并返回，DocumentationType 即文档类型的选择我们需要根据集成的 Swagger 的版本来选择，这里选择 `SWAGGER_2` 表示使用的 Swagger 是`2.X`系列版本。

*  `apis()` 方法里面通过 `RequestHandlerSelectors.basePackage()` 属性来描述我们的目标包，就是我们项目中接口所在包的完整目录名称，这样 Swagger 就可以扫描到了，如果不配置此项，Swagger 是扫描不到我们项目中的接口的。
 *  `paths()` 方法就是规定将我们项目中`所有接口的请求路径`都暴露给 Swagger 来生成 Swagger-UI 界面。
 *  `build()` 方法就是将我们设置的上述参数都放到返回的 Docket 实例中。

**2、apiInfo()**  
返回 Swagger-ApiInfo 类型，即返回 Swagger-UI 界面的基本信息。在方法内部也是通过匿名内部类的方式返回一个 ApiInfo 实例。

*  `title()` 方法：就是来规定我们的 Swagger-UI 界面的`大标题`。
 *  `description()` 方法：就是来规定对 Swagger-UI 界面的一些`简单描述信息`。
 *  `contact()` 方法：就是来规定创建 Swagger-UI 的`作者的名称`，目前已被废弃。
 *  `version()` 方法：就是来规定 Swagger-UI 界面上`所有接口的版本`。
 *  `build()` 方法：就是将我们设置的上述参数都放到返回的 ApiInfo 实例中。

# 0x02 检验Swagger #

##### 1. 启动项目 #####

（1）访问端口：`http://localhost:8080/swagger-ui.html#/`，可以看到界面。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NoYW9jazIwMTg_size_16_color_FFFFFF_t_70]

# 0x03 第一个例子 #

##### 1. 添加注解 #####

项目参考文章：[SpringBoot+Thymeleaf+ECharts实现大数据可视化（基础篇）][SpringBoot_Thymeleaf_ECharts]

主要是添加注解，完整代码如下：

package com.example.controller;
    
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestMethod;
    import org.springframework.web.bind.annotation.RestController;
    
    /** * @Auther: shaonaiyi@163.com * @Date: 2020/8/23 23:10 * @Description: UserController控制器 */
    @Api(tags = "用户管理")
    @RestController()
    @RequestMapping(value = "/user/")
    public class UserController { 
    
        @ApiOperation(value = "用户登录",notes = "必须使用post方法")
        @RequestMapping(value = "login.do",method = RequestMethod.POST)
        public String login(){ 
            return "login";
        }
    
    }

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NoYW9jazIwMTg_size_16_color_FFFFFF_t_70 1]

##### 2. 查看结果 #####

访问：`http://localhost:8080/swagger-ui.html#`，然后点开`用户管理`，可以看到内容：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NoYW9jazIwMTg_size_16_color_FFFFFF_t_70 2]

# 0xFF 总结 #

1.  本教程主要是介绍Swagger的配置与简单使用，具体的内容，还是需要结合实际项目才能解释得清。

> **邵奈一** 原创不易，如转载请标明出处，教育是一生的事业。

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

[Link 1]: https://blog.csdn.net/shaock2018/article/details/89349249
[Link 2]: https://img-blog.csdnimg.cn/20190608000417972.jpeg?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NoYW9jazIwMTg=,size_16,color_FFFFFF,t_70
[Link 3]: https://img-blog.csdnimg.cn/20190514084602748.png
[Link 4]: https://weibo.com/5680168183/
[CSDN]: https://blog.csdn.net/shaock2018
[Link 5]: https://www.jianshu.com/u/6f033c6a3b90
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NoYW9jazIwMTg_size_16_color_FFFFFF_t_70]: /images/20210923/236fb1b55fa246089f44e299f02fa396.png
[SpringBoot_Thymeleaf_ECharts]: https://blog.csdn.net/shaock2018/article/details/86706101
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NoYW9jazIwMTg_size_16_color_FFFFFF_t_70 1]: /images/20210923/d29f30cea7754f3bad08ba1b3251f41e.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NoYW9jazIwMTg_size_16_color_FFFFFF_t_70 2]: /images/20210923/0b0950e49deb43d184928e95fcdd1fbd.png