Java Spring框架-Swagger UI文档整合

说明

        最近被拉入一个项目组写API，用到了一个Swagger的文档框架，自动化文档，有效减少前后端交流。这个框架的好处就是可以通过注解代码来生成API文档，尤其适合RESTful项目。

参考文章以及书籍

Swagger使用指南
Swagger原理解析

什么是SwaggerUI？

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.
简单的说，就是在文档跟随代码，API文档具备调用测试RESTful接口的能力。

当项目启动之后，你可以通过访问 http://localhost:8000/swagger-ui.html# 网址来查看项目的文档以及调用项目所提供的接口。

访问方法，model属性，传入参数，测试

你可以通过对上述接口传入参数，然后 Try it out。

请求，响应

在项目中配置这种能力

SpringMVC很好地支持这种文档生成的能力，使用Springfox，首先加入maven包

<!– sring mvc依赖 –>
<dependency>
   <groupId>org.springframework</groupId>
   <artifactId>spring-webmvc</artifactId>
   <version>4.2.8.RELEASE</version>
</dependency>

<!– swagger2核心依赖 –>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.6.1</version>
</dependency>

<!– swagger-ui为项目提供api展示及测试的界面 –>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.6.1</version>
</dependency>

加入配置类

@Configuration
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * 
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swaggerTest.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("更多请关注http://www.baidu.com")
                .termsOfServiceUrl("http://www.baidu.com")
                .contact("sunf")
                .version("1.0")
                .build();
    }
}

这样就可以访问 http://127.0.0.1:8080/xxxx/swagger-ui.html
很好地自动化体验。

书写API文档的步骤

• 命名使用英文，不要使用中文首字母。上图的API可以作为反面教材，无奈项目早期数据库设计使用了这种方式，项目成员决定省事沿用。

• 在Controller上加上@Api
  

  对应生成下面的一项

一条@Api,用来书写API方法

• 在对应的Controller方法上加上@ApiOperation

一条Operation对应一条API方法 Operation底下说明该方法的一些信息

• 在方法使用的实体添加@ApiModelProperty

ApiModelProperty注解对应返回的实体对象 对应ApiModelProperty

Springfox-Swagger原理分析

[这一部分并没有完成，等稍微空闲在做学习。如果感兴趣可以去参考博文那进行阅读]

springfox的大致原理就是，在项目启动的过种中，spring上下文在初始化的过程，框架自动跟据配置加载一些swagger相关的bean到当前的上下文中，并自动扫描系统中可能需要生成api文档那些类，并生成相应的信息缓存起来。如果项目MVC控制层用的是springMvc那么会自动扫描所有Controller类，根据这些Controller类中的方法生成相应的api文档。

回头看配置类

@Configuration
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig {

}

这个类中没有任何代码，很显然，三个注解起了至关重要的作用。
其中@Configuration注解是spring框架中本身就有的，它是一个被@Component元注解标识的注解，所以有了这个注解后，spring会自动把这个类实例化成一个bean注册到spring上下文中。
第二个注解@EnableWebMvc故名思义，就是启用springmvc了，在Eclipse中点到这个注解里面简单看一下，它就是通过元注解@Import(DelegatingWebMvcConfiguration.class)往spring context中塞入了一个DelegatingWebMvcConfiguration类型的bean。我想，这个类的目的应该就是为swagger提供了一些springmvc方面的配置吧。
第三个注解：@EnableSwagger2，看名字应该可以想到，是用来集成swagger2的，他通过元注解：@Import({Swagger2DocumentationConfiguration.class})，又引入了一个Swagger2DocumentationConfiguration类型的配置bean，而这个就是Swagger的核心配置了。

@Configuration
@Import({ SpringfoxWebMvcConfiguration.class, SwaggerCommonConfiguration.class })
@ComponentScan(basePackages = {
    "springfox.documentation.swagger2.readers.parameter",
    "springfox.documentation.swagger2.web",
    "springfox.documentation.swagger2.mappers"
})

publicclassSwagger2DocumentationConfiguration {
  @Bean
  public JacksonModuleRegistrar swagger2Module() {
    returnnewSwagger2JacksonModule();
  }
}