SpringBoot集成Swagger构建api文档

最近在做项目的时候，一直用一个叫做API的东西，controller注解我会写，这个东西我也会用，但是我确实不知道这个东西是个什么，有点神奇。关键还坑了我一次，他的注解会影响到代码的运行，不光是起到注解的作用。所以我就研究了一下。

Swagger是什么：THE WORLD’S MOST POPULAR API TOOLING

根据官网的介绍：
Swagger Inspector：测试API和生成OpenAPI的开发工具。Swagger Inspector的建立是为了解决开发者的三个主要目标。

1. 执行简单的API测试
2. 生成OpenAPI文档
3. 探索新的API功能

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

1. Swagger可以整合到代码中，在开发时通过注解，编写注释，自动生成API文档。
2. 将前端后台分开，不会有过分的依赖。
3. 界面清晰，无论是editor的实时展示还是ui的展示都十分人性化，如果自己仅仅用markdown来编写，又要纠结该如何展现，十分痛苦。

下面的两点我还没有进行实践：

1. 支持Json和yaml来编写API文档，并且支持导出为json、yaml、markdown等格式
2. 如果编写好了API了，可以自动生成相应的SDK，没错，可能你的API接口代码还没有开始写，它就能帮你制作相应的SDK了，而且支持几乎所有主流编程语言的SDK。

SpringBoot,Maven构建SwaggerAPI文档

第一步：创建SpringBoot Web项目

在这里就不过多进行介绍，只是说一下可能出现的问题：创建好项目之后目录结构不对，只有src/main/resources文件夹。下图所示
：
这时候只需要将JDK版本升级到你安装的版本就可以，其他文件夹就可以显现出来：

第二步：创建类以及配置pom.xml

1：配置pom.xml，添加依赖包：

第一个是API获取的包，第二是官方给出的一个ui界面。三和四是spring boot 需要的jar包。

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

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>

2：配置Swagger，创建SwaggerConfig.java类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com"))
            .paths(PathSelectors.any()).build();
}


private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        .title("Spring Boot中使用Swagger2构建RESTful APIs")
        .description("myapp")
        .termsOfServiceUrl("http://blog.csdn.net/java_yes")
        .version("1.0").build();
    }
}

这里有个特别需要注意的地方：
RequestHandlerSelectors.basePackage(“com.swagger”)，这是扫描注解的配置，即你的API接口位置。文章最后我会做总结。

3：创建SpringBoot启动类

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

4：创建controller

在这里我创建两个controller，为了解释@RequestMapping();这两个Controller没有任何实际意义，可以随意创建，我只是为了测试SwaggerAPI

GreetingController

@RestController
@RequestMapping(value = "/test")
public class GreetingController {
    private static final String template = "Hello, %s!";
    private final AtomicLong counter = new AtomicLong();

    @RequestMapping(value = "/swagger")
    //@RequestMapping("/swagger")
    //@RequestMapping(value = "/swagger",method = RequestMethod.POST)
    public Greeting greeting(@RequestParam(value = "name", defaultValue = "World") String name) {
        return new Greeting(counter.incrementAndGet(), String.format(template, name));
    }
}

BookController

@RestController
@Api(tags = "BookController", description = "BookController | 通过书来测试swagger")
@RequestMapping(value = "/books")
public class BookController {

    Map<Long, Book> books = Collections.synchronizedMap(new HashMap<Long, Book>());

    @ApiOperation(value="创建图书", notes="创建图书")
    @ApiImplicitParam(name = "book", value = "图书详细实体", required = true, dataType = "Book")
    @RequestMapping(value="", method=RequestMethod.POST)
    public String postBook(@RequestBody Book book) {
        books.put(book.getId(), book);
        return "success";
    }

    @ApiOperation(value = "获图书细信息", notes = "根据url的id来获取详细信息")
    @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Long", paramType = "path")
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    public Book getBook(@PathVariable Long id) {
        return books.get(id);
    }
}

5：创建SpringBoot 启动类：

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

第三步：启动Swagger

OK，到此为止，整个Swagger我们已经配置完毕。此时访问http://localhost:8080/swagger-ui.html#/greeting-controller。就可以看到Swagger-UI了。如下图所示

同样，根据@RequestMapping()的路径我们可以进行访问，再API中进行测试一样。这里我就进行演示。

坑！！！！我在配置过程中出现的错误；

我先发一下我的文件结构：

1：什么都配置了，但是API什么都不显示。如图所示：

这个就是我上面说到的问题：RequestHandlerSelectors.basePackage(“com.swagger”)
这个地方配置的是你swagger要加载的接口所在的包名。会去扫秒这个包下的所有Controller。大家看我的文件结构。
如果你配置的是RequestHandlerSelectors.basePackage(“com”)，那么就会扫描所有com包下的Controller，包括com.swagger;以及com.controller。效果就是这样：

如果你只是单独配置RequestHandlerSelectors.basePackage(“com.swagger”),或者RequestHandlerSelectors.basePackage(“com.swagger”)。那么就会显示一个。

2：我配置的是RequestHandlerSelectors.basePackage(“com”)，但API还是只显示一个，而且不显示Controller直接访问地址也报错，如图所示：

这个时候可能是SpringBoot的问题了。他并没有加载到你的另一个controller。
SpringBoot启动类和Controller类需要在同一包下，controller要在父类包下。
这个时候有两种解决方案：

1. 将未加载的Conrtoller类移动到SpringBoot启动类所在包。或者将其包名改为启动类的子包。
2. 如上述代码，在启动类上加注释：@ComponentScan(basePackages={“com”})。该注释会扫描所有com包下的controller并加载。

为什么我GreetingController没有写rest方法。但是API中显示了所有呢？

这个要用@RequestMapping();进行解释了。

1. @RequestMapping(value = “/swagger”)或者@RequestMapping(“/swagger”)这么写的时候，就会加载所有method。
2. @RequestMapping(value = “/swagger”,method = RequestMethod.POST)，当你自己设置mathod的时候，就会只创建你设置的method。