SpringBoot整合Swagger

一、Swagger介绍

Swagger是一个RESTful API的工具，目标是为REST API定义一个标准的、与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下，能发现和理解各种服务的功能。通过Swagger可以获得项目的一种交互式文档，客户端SDK的自动生成等功能。

Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。Swagger已经是世界上最流行的API表达工具。

使用Spring Boot集成Swagger的理念是，使用注解标记出需要在API文档中展示的信息，Swagger会根据项目中标记的注解来生成对应的API文档。

二、Spring Boot集成Swagger

Spring Boot 集成 Swagger 2.X 很简单，需要引入依赖并做基础配置即可，下面我们来感受一下。

A、相关依赖

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

B、配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //  swagger访问地址http://localhost:端口号/程序上下文/swagger-ui.html
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("org.school.examination.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("在线考试系统")
                //创建人
                .contact(new Contact("教育", "http://blog.csdn.net/m0_37876631", "[email protected]"))
                //版本号
                .version("1.0")
                //描述
                .description("接口信息")
                .build();
    }

}

@EnableSwagger2，表示此项目启用Swagger API文档。

在启动时初始化，返回实例Docket（Swagger API摘要），需要指定扫描的包路径，只有此路径下的Controller类才会自动生成Swagger API文档。

C、在Controller层增加相关注解

@RestController
@Api(value = "学科信息相关接口", tags = "学科信息相关接口")
public class SubjectController {

    private Logger logger = LoggerFactory.getLogger(SubjectController.class);

    @Autowired
    private SubjectService subjectService;

    @GetMapping(value = "/getSubject.do")
    @ApiOperation(value = "获取学科信息", notes = "获取学科信息")
    public String getSubject() {
        ......
    }

    @PostMapping(value = "/saveSubject.do")
    @ApiOperation(value = "保存学科信息", notes = "保存学科信息")
    public String saveSubject(@RequestBody SubjectEntity entity) {
        ......
    }
}

配置完成之后启动项目，访问http://localhost:8088/examination/swagger-ui.html，即可看到Swagger的UI效果。