Swagger介绍及使用

什么是Swagger：

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。通俗的讲，Swagger 就是将项目中所有接口（想要暴露出去的接口）展现在页面上，并且可以进行接口调用和测试的服务。

好处：

1、后端程序员就不需要专门为前端使用者编写专门的接口文档；

2、当接口更新之后，只需要修改代码中的 Swagger 描述就可以实时生成新的接口文档了；

3、可以直接进行接口调用，降低了项目开发阶段的调试成本。

Swagger的使用：

1、先写controller方法，如下：

package com.atzh.springboot3.controller;

import com.atzh.springboot3.pojo.User;
import org.springframework.web.bind.annotation.*;

import java.util.*;

@RestController
@RequestMapping(value = "/users")
public class UserController {

    // 创建线程安全的Map，模拟users信息的存储
    static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());

    // 处理"/users/"的GET请求，用来获取用户列表
    @GetMapping("/")
    public List<User> getUserList() {
        // 还可以通过@RequestParam从页面中传递参数来进行查询条件或者翻页信息的传递
        List<User> r = new ArrayList<User>(users.values());
        return r;
    }

    // 处理"/users/"的POST请求，用来创建User
    @PostMapping("/")
    public String postUser(@RequestBody User user) {
        // @RequestBody注解用来绑定通过http请求中application/json类型上传的数据
        users.put(user.getId(), user);
        return "success";
    }

    // 处理"/users/{id}"的GET请求，用来获取url中id值的User信息
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        // url中的id可通过@PathVariable绑定到函数的参数中
        return users.get(id);
    }

    //处理"/users/{id}"的PUT请求，用来更新User信息
    @PutMapping("/{id}")
    public String putUser(@PathVariable Long id, @RequestBody User user) {
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "success";
    }

    // 处理"/users/{id}"的DELETE请求，用来删除User
    @DeleteMapping("/{id}")
    public String deleteUser(@PathVariable Long id) {
        users.remove(id);
        return "success";
    }

}

2、再导入依赖，如下：

<!-- https://mvnrepository.com/artifact/com.spring4all/swagger-spring-boot-starter -->
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>2.0.1.RELEASE</version>
</dependency>

3、修改配置文件，如下：

swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.4.0.RELEASE
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-test
swagger.contact.name=atzh
swagger.contact.url=https://blog.csdn.net/weixin_46208769
swagger.contact.email=512142900@qq.com
swagger.base-package=com.atzh
swagger.base-path=/**

• swagger.title：标题
• swagger.description：描述
• swagger.version：版本
• swagger.license：许可证
• swagger.licenseUrl：许可证URL
• swagger.termsOfServiceUrl：服务条款URL
• swagger.contact.name：维护人
• swagger.contact.url：维护人URL
• swagger.contact.email：维护人email
• swagger.base-package：swagger扫描的基础包
• swagger.base-path：需要处理的基础URL规则

4、别忘了在主启动方法上加@EnableSwagger2Doc注解，开启swagger服务

@EnableSwagger2Doc
@SpringBootApplication
public class SpringBoot3Application {
    public static void main(String[] args) {
        SpringApplication.run(SpringBoot3Application.class, args);
    }
}

5、启动服务，并在浏览器输入网址：http://localhost:8080/swagger-ui.html

此时swagger就可以使用了。

6、web端简单操作教程，如下：以post请求为例，其他的一样道理。