springboot+swagger2+RestFul风格接口

swagger2简介

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了前后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系，变成了 API 接口，所以 API 文档变成了前后端开发人员联系的纽带，变得越来越重要。那么问题来了，随着代码的不断更新，开发人员在开发新的接口或者更新旧的接口后，由于开发任务的繁重，往往文档很难持续跟着更新，Swagger 就是用来解决该问题的一款重要的工具，对使用接口的人来说，开发人员不需要给他们提供文档，只要告诉他们一个 Swagger 地址，即可展示在线的 API 接口文档，除此之外，调用接口的人员还可以在线测试接口数据，同样地，开发人员在开发接口时，同样也可以利用 Swagger 在线接口文档测试接口数据，这给开发人员提供了便利。

Swagger2注解

1. 实体类注解

@ApiModel 注解用于实体类，表示对类进行说明，用于参数用实体类接收。

@ApiModelProperty注解用于类中属性，表示对 model 属性的说明或者数据操作更改。

@ApiModel(value = "用户实体类")
public class User {
    @ApiModelProperty(value = "用户姓名")
    private String userName;

    @ApiModelProperty("手机号码")
    private String phone;

    @ApiModelProperty("年龄")
    private int age;
    
    //省略set()  get()
}

2 .Controller 类中相关注解

@Api 注解用于类上，表示标识这个类是 swagger 的资源。

@ApiOperation 注解用于方法，表示一个 http 请求的操作。

@ApiParam 注解用于参数上，用来标明参数信息。

@RestController
@RequestMapping("/test")
@Api(value = "test API接口")
public class Test {
    @PostMapping("/user")
    @ApiOperation(value = "获取用户")
    public void getUser(@RequestBody @ApiParam(value = "用户实体")User user){
        System.out.println(user.getUserName());
        System.out.println(user.getPhone());
        System.out.println(user.getAge());
    }
}

效果

引入依赖

		<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>

配置swagger2

新建swagger2类

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sunny.cloud.user.controller")) //接口路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restful风格，https://blog.csdn.net/weixin_44020899/article/details/103752276")
                .termsOfServiceUrl("http://blog.csdn.net/forezp")
                .version("1.0")
                .build();
    }
}

访问页面查看

在页面输入http://localhost:8080/swagger-ui.html