Swagger的使用(第一个案例)

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


教程目录

0x00 教程内容
0x01 配置Swagger
1. 添加 Swagger 依赖

(1)在pom.xml文件中导入 swagger 依赖:

<!-- 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#/,可以看到界面。
Swagger的使用(第一个案例)

0x03 第一个例子
1. 添加注解

项目参考文章: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";
    }

}

Swagger的使用(第一个案例)

2. 查看结果

访问:http://localhost:8080/swagger-ui.html#,然后点开用户管理,可以看到内容:
Swagger的使用(第一个案例)

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

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


上一篇:.NET WebSockets 核心原理初体验


下一篇:Javascript 实现的StopWatch