SpringBoot整合Swagger

@Author:SimpleWu

什么是Swagger？

Swagger是什么：THE WORLD’S MOST POPULAR API TOOLING 根据官网的介绍： Swagger Inspector：测试API和生成OpenAPI的开发工具。Swagger Inspector的创建是为了解决开发者的三个主要目标。

• 执行简单的API测试
• 生成OpenAPI文档
• 探索新的API功能

个人理解Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。简单来讲，Swagger是一个功能强大的接口管理工具，而且提供了多种编程语言的先后端分离解决方案。根据个人使用，固然我只是最简单的使用，我感受Swagger有如下几个优势：

Swagger能够整合到代码中，在开发时经过注解，编写注释，自动生成API文档。 将前端后台分开，不会有过度的依赖。

界面清晰，不管是editor的实时展现仍是ui的展现都十分人性化，若是本身仅仅用markdown来编写，又要纠结该如何展示，十分痛苦。

构建项目

step1.导入依赖

<!--swagger服务api构建个性包-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.6.1</version>
    </dependency>
	<!--swagger ui界面-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.6.1</version>
    </dependency>
	<!--springboot web服务-->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
	<!--springboot单元测试-->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>

step2.编写swagger配置类

想要使用swagger功能必须提供配置类，主要配置ui界面信息，以及配置扫描位置，swagger会根据配置的路径扫描全部的服务生成api。

其中核心RequestHandlerSelectors.basePackage("com.simple.spring.boot.controller"),在这里配置咱们的须要的扫描包位置。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.simple.spring.boot.controller"))
            .paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        .title("Spring Boot中使用Swagger2构建RESTful APIs")
        .description("myapp")
        .termsOfServiceUrl("http://blog.csdn.net/SimpleWu")
        .version("1.0").build();
    }
}

step3.编写springboot启动类

@ComponentScan(basePackages={"com.simple.spring.boot.controller"}) 也是须要配置扫描路径。

@SpringBootApplication
@ComponentScan(basePackages={"com.simple.spring.boot.controller"})  
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }
}

step4.建立前端控制器

@RestController
@Api(tags = "swgger测试服务", description = "swgger测试服务")
@RequestMapping(value = "/simple/wu")
public class TestController {

    @ApiOperation(value="测试POST方法", notes="测试POST方法")
    @ApiImplicitParam(name = "令牌", value = "ID", required = true, dataType = "token")
    @RequestMapping(value="hello", method=RequestMethod.POST)
    public String post(@RequestBody String token) {
        books.put(book.getId(), book);
        return "success";
    }
}

1. @Api(tags = "swgger测试服务", description = "swgger测试服务") 指定某个类提供服务的名字
2. @ApiOperation(value="测试POST方法", notes="测试POST方法") 指定某个请求的名字
3. @ApiImplicitParam(name = "令牌", value = "token", required = true, dataType = "String")指定名字对应参数为令牌，以及对应参数字段token，required = true表明这个参数为必填参数，dataType 表明数据类型。

step5.启动服务

从上面的代码中咱们指定请求为POST在UI界面上咱们会看到一个服务名字为swgger测试服务的大类点击进去后能够看到里面所拥有的请求，若是指定这个请求的类型那么没法进行单元测试，指定后咱们会看到一个请求名字叫作测试POST方法的请求而且须要填入必填参数token来完成咱们的单元测试。

咱们能够直接经过SwaggerApplication类来运行main方法来进行服务，端口号默认为8080.

swagger地址：http://localhost:8080/swagger-ui.html 只须要在地址后面加上swagger-ui.html便可访问

咱们访问这个位置便可看到UI界面，界面简洁而且容易上手，我这边就不截图了。

step.总结

swagger官方文档:https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api

swagger的一个最大的优势是能实时同步api与文档。

在项目开发过程当中，发生过屡次：修改代码可是没有更新文档，前端仍是按照老旧的文档进行开发，在联调过程当中才发现问题的状况（固然依据开闭原则，对接口的修改是不容许的，可是在项目不稳定阶段，这种状况很难避免）。

原文出处：https://www.cnblogs.com/SimpleWu/p/10261140.html