博客

一、Swagger介绍

dfdfd


编写和维护接口文档是每个程序员的职责，根据Swagger2可以快速帮助我们编写最新的API接口文档，再也不用担心开会前仍忙于整理各种资料了，间接提升了团队开发的沟通效率。

二、Swagger教程

1.创建SpringBoot项目，pom.xml中添加依赖

    <dependency>
            <!--添加Swagger依赖 -->
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
    </dependency>

    <dependency>
            <!--添加Swagger-UI依赖 -->
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
    </dependency>

    <dependency>
            <!--添加热部署依赖 不加也行-->
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
    </dependency>

2. 在启动类的同级创建一个Swagger的配置类

@Configuration   // 声明配置类 
@EnableSwagger2  // 开启在线接口文档
public class Swagger2Config {
    @Bean //用在方法上告诉Spring容器，你可以从下面这个方法中拿到一个Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())                
                .select()  // 函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.web"))  //扫描包下所有带Controller的api 除了@ApiIgnore
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 此方法会在页面展示api信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("用户的CRUD")
                .termsOfServiceUrl("放个链接")
                .version("1.0")
                .build();
    }
}

3. 创建自己的web层的controller

@Api("用户信息管理")  // 描述接口的类型
@RestController  
@RequestMapping("/users")
public class UserController {

    private final static List<User> userList = new ArrayList<>();

    {   // 添加数据
        userList.add(new User("1", "admin", "123456"));
        userList.add(new User("2", "jacks", "111111"));
    }

    @ApiOperation("获取列表")  // 描述方法的用途
    @GetMapping("list")
    public List userList() {
        return userList;
    }

    @ApiOperation("新增用户")
    @PostMapping("save")
    public boolean save(User user) {
        return userList.add(user);
    }

    @ApiOperation("更新用户")
    @ApiImplicitParam(name = "user", value = "单个用户信息", dataType = "User")  // 描述方法的参数
    @PutMapping("update")
    public boolean update(User user) {
        return userList.remove(user) && userList.add(user);
    }

    @ApiOperation("批量删除")
    @ApiImplicitParam(name = "users", value = "N个用户信息", dataType = "List<User>") //  @apiImplicitParam 描述方法的参数(Multi-Params)
    @DeleteMapping("delete")
    public boolean delete(@RequestBody List<User> users) {
        return userList.removeAll(users);
    }


}

4. User类

public class User implements Serializable{

     private String userId;
     private String username;
     private String password;
    // 省略 getter  setter
}

5. 注解介绍

@Api // 描述类/接口的主要用途
@ApiOperation // 描述方法用途
@ApiImplicitParam // 描述方法的参数
@ApiImplicitParams // 描述方法的参数(Multi-Params)
@ApiIgnore // 忽略某类/方法/参数的文档

6. 结果

编写文档完成之后，启动当前项目，在浏览器打开：

[

http://localhost:8080/swagger-ui.html

] , 看到效果如下：

啥！你问我为什么访问路径带个html，那你看这里：

在这个web页面上，点击try it out 可以在这里进行测试！