开启掘金成长之旅！这是我参与「掘金日新计划 · 12 月更文挑战」的第32天，点击查看活动详情

引言

后端修改了接口，需要手动维护api文档，加大了开发的工作量和困难，而swagger的出现就是为了解决这一系列的问题。

swagger是一套基于OpenAPI规范构建的开源工具，使用RestApi

代码变，文档变
跨语言，支持多种语言
swagger-ui 呈现出来的是一份可交互式的API文档，可以直接在文档页面尝试API的调用
可以将文档规范导入相关工具（postman、soapui），这些工具将会为我们自动地创建自动化测试

RestApi格式是根据请求的方式决定本次请求的一个操作，譬如：get-->读，post-->写（增、删、改），put-->修改，delete-->删除。www.ibm.com/cn-zh/cloud…

OpenApi与语言无关，只是一种规范，可以使用yaml和json格式进行编写，这样更利于我们和机器进行阅读

I Swagger

1.1 组成部分

swagger主要包含了以下三个部分：

swagger editor：基于浏览器的编辑器，我们可以使用它编写我们OpenApi规范(yaml或者json配置）
Swagger UI：他会将我们编写的OpenApi规范呈现为交互式的API文档，后文我将使用浏览器来查看并且操作我们的RestApi
Swagger Codegen：它可以通过OpenApi规范定义的任何API生成服务器存根和客户端SDK来简化构建过程

swagger的使用: 使用swagger就是把相关信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件去更新接口文档，以及生成各端代码。

1.2 springfox

Spring-fox是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码即可，而不需要跟随修改描述文件(yml或json文件）;

spring-fox利用自身AOP特性，把swagger集成进来，底层还是Swagger，但是使用起来却方便很多，所以在实际开发中，都是直接使用spring-fox。

导入依赖

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

启动类中添加@EnableSwagger2注解

@enableSwagger2：是springfox提供的一个注解，代表swagger2相关技术开启,会扫描当前类所在包，以及子包中所有的类型中的注解，做swagger文档的定值

@Configuration //声明该类为配置类
@EnableSwagger2 //声明启动Swagger2
public class SwaggerConfig {

启动项目，并在浏览器输入http://localhost:端口/swagger-ui.html进行swagger-ui界面访问

II 注解

2.1 接口标签（分类）

@Api(tags="重新定位限制")

2.2 接口说明

@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response =
“接口返回参数类型”, notes = “接口发布说明”；其他参数可参考源码；

例子

    @PostMapping("")
    @ApiOperation("登录接口")
    public ServerResponse Login(@RequestBody UserLoginDto userLoginDto){
    
    }

java小技能：Swagger （RESTful 风格的 Web 服务框架）

引言