SpringBoot 使用 swagger 实现Rest Api 文档化

swagger 允许用户在一个html5 web 页面中，对API 进行文档化和交互
优点：
功能丰富 ：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；
及时更新 ：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；
整合简单 ：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。

实现 swagger 文档

1. 添加依赖
   主要是 添加 swagger2 核心包 以及 swagger-ui界面包 的依赖

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

2. 配置 api 页面的基本信息

/**
 * Created by Sean on 2018/10/10
 *Api 文档页面 基本信息
 * 可以通过注解注入相关配置。
 * 通过这些配置可以指定在spring-boot启动时扫描哪些controller层的文件夹，
 * 另外可以指定API文档页的标题和描述信息等内容
 * @author Sean
 */
@Configuration
@EnableSwagger2
public class Swagger2 {


    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.voicecyber"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title(" RESTful APIs")
                .description(" Rest  Server api接口文档")
                .version("1.0")
                .build();
    }
}

3. 将swagger-ui 暴露到spring boot环境 主要是配置spring mvc 的一些资源拦截

/**
 * Created by Sean on 2018/10/10
 *将swagger-ui中的界面配置至spring-boot环境
 * @author Sean
 */
@Component
public class WebMvcConfig extends WebMvcConfigurerAdapter {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/js/**").addResourceLocations("classpath:/js/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

4. 在controller 中编写自己的api 文档 主要在于参数，和接口的描述

@Api(value = "RestApi", description = "Rest Api Server")
@RestController
@RequestMapping("api")
public class RestApiController {
    /**
     *需要注意的是  必须指定 RequestMethod  的具体类型，不然前端会显示多种类型的Rest
     */
    @ApiOperation(value = "信息总览", notes = "用户信息总览")
    @ApiImplicitParam(name = "type", value = "获取信息的类型（name ,sex）", paramType = "query", dataType = "string")
    @RequestMapping(value = "info", method = RequestMethod.GET)
    @ResponseBody
    public ResponseEntity getUserInfo(String type) {
        System.out.println(type);
        return new ResponseEntity("this is user info ", HttpStatus.OK);
    }
   }

5. .配置properties 文件
   这个文件配置非常重要 ，主要在于
   springfox.documentation.swagger.v2.host 的配置非常重要，在访问的swagger-ui.html 页面时。如果访问的路径不统一，那么可能会发生跨域的问题

springfox.documentation.swagger.v2.host=127.0.0.1:8080
springfox.documentation.swagger.v2.path=/api
server.port=8080
server.context-path=/rest

6. 访问页面
   使用上面的host 路径 再加上 swagger-ui.html 即可访问页面http://127.0.0.1:8080/swagger-ui.html
   github url：springbootrestswagger