Swagger 的简介和使用

Swagger 的简介和使用

什么是Swagger

简介

wagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档。
后端开发要为前端提供接口，同时还需要提供接口的说明文档。但我们的代码总是会根据实际情况来实时更新，这个时候有可能会忘记更新接口的说明文档，造成一些不必要的问题。
归根到底，swagger就是帮助我们自动写接口说明文档的。更具体地，可以看下面的图片，swagger官方建议使用下面的红字部分。

Swagger页面

我们简单了解下，swagger的页面中各个元素的含义

Swagger快速上手

pom.xml文件中引入依赖

<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.8.0</version>
        </dependency>

构建Swagger配置类

/**
 * @auther Bachelor_HT
 * @date 2023/6/23 14:43
 * @desc default
 */
@Configuration
public class SwaggerConfigruationSettinngs {
    //创建Docket对象
    @Bean
    public Docket docket() {
        //1创建Docket对象
        Docket docket = new Docket(DocumentationType.SWAGGER_2);

        //2创建Api信息， 接口文档的总体描述
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("动力节点金融项目")
                .version("1.0")
                .description("前后端分离的项目，前端Vue，后端Spring Boot + Dubbo分布式项目")
                .build();

        //3.设置使用ApiInfo
        docket = docket.apiInfo(apiInfo);

        //4.设置参与文档生成的包
        docket = docket.select().apis(RequestHandlerSelectors.
                basePackage("com.ht.front.controller")).build();

        return docket;

    }
}

补充说明：

• apiInfo：api基本信息的配置，信息会在api文档上显示，可有选择的填充，比如配置文档名称、项目版本号等
• apis：使用什么样的方式来扫描接口，RequestHandlerSelectors下共有五种方法可选。我们当前使用通过在类前添加@Api注解的方式，其他方法我们后续介绍。
• path：扫描接口的路径，PathSelectors下有四种方法，我们这里是全扫，其他方法我们后续介绍。

Swagger使用

常用注解说明

注解	说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty

注解的使用

举一个简单的例子，涵括了以上大部分注解：

/**
 * @auther Bachelor_HT
 * @date 2023/6/26 0:52
 * @desc default
 */
@Api(value = "用户功能")
@RestController
@RequestMapping("/v1/user")
public class UserController extends baseController {

    @ApiOperation(value = "手机号注册")
    @PostMapping("/register")
    public RespResult userRegister(@RequestParam String phone,
                                   @RequestParam String pword,
                                   @RequestParam String smscode) {
			return null;
    }
}

执行上述代码，在输入http://localhost:8000/api/swagger-ui.html,点击对应的接口，就可以看到：

总结

Swagger简单，易上手，是居家旅行必备良药。使用Swagger大大提升了我们的工作效率，加快开发进度，减少在开发时导致超出预期的概率，个人强烈建议！！！后续发一篇Swagger注解的详细说明。