Swagger在Springboot中的入门使用

swagger

swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。swagger 让部署管理和使用功能强大的API从未如此简单。

过程容易踩到的坑

1. 过滤器拦截静态资源
2. 静态资源存放位置
3. 注解@EnableSwagger2的使用
4. 浏览器不兼容

---

在Springboot中整合Swagger

1 添加依赖

    <dependency> <!--添加Swagger依赖-->
        <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>

2 配置SwaggerConfig

package com.example.springbootdemo;

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()                                   //此处记得替换需要扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.example.springbootdemo.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")//页面标题
                .description("简单优雅的RESTful风格")//描述
                .version("1.0")//版本号
                .build();
    }
}

3 配置开启Swagger

@EnableSwagger2 //  ← 特别重要不然无限报错
@SpringBootApplication
public class SpringbootdemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringbootdemoApplication.class, args);
    }
}

4 在Controller类中进行注解

@RestController
@RequestMapping("/basecontroller/")
@Api("textControllerapi")
public class BaseController {

    @ApiOperation(value="获取用户列表", notes="获取该用户权限能查看的用户列表")
    @GetMapping("findUserList")
    public  List<User> findUserList() {
        //...无关细节省略
        return userRepository.findAll(Example.of(user1,matcher));
    }
}

5 访问静态网址

运行项目
访问http://localhost:8080/swagger-ui.html

swagger-ui.html
1. 是由 springfox-swagger-ui 包引入
2. 可自定义; 修改为中文或修改样式
3. 属于静态资源会被拦截器拦截
4. idea中默认不带项目名(需自行检查)

访问后如下

6 常用注解

注解名称	使用场景
@Api	用于类；表示标识这个类是swagger的资源
@ApiModel	用于类；表示标识这个类是接收参数的实体类
@ApiOperation	用于方法；表示一个http请求的操作
@ApiImplicitParam	用于方法；表示单独的请求参数
@ApiImplicitParams	用于方法；包含多个 @ApiImplicitParam