springcloud 集成Swagger

 

1      什么是Swagger？

Swagger™的目标是为REST APIs 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。

2      springboot集成Swagger

2.1  构建springboot项目

使用Spring Boot构建一个RESTful APIs和单元测试，具体代码参看附件中的Swagger-test项目。此处不再赘述。

2.2  集成Swagger

1.     添加Swagger2依赖

在pom.xml中加入Swagger2的依赖

<dependency>

   <groupId>io.springfox</groupId>

   <artifactId>springfox-Swagger2</artifactId>

   <version>2.2.2</version>

</dependency>

<dependency>

   <groupId>io.springfox</groupId>

   <artifactId>springfox-Swagger-ui</artifactId>

   <version>2.2.2</version>

</dependency>

2.       创建Swagger2配置类

在Application.java同级创建Swagger2的配置类Swagger2。

@Configuration

@EnableSwagger2

public class Swagger2{

 

   @Bean

   public Docket createRestApi() {

        return newDocket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())

                .select()

               .apis(RequestHandlerSelectors.basePackage("com.didispace.web"))

                .paths(PathSelectors.any())

                .build();

   }

 

   private ApiInfo apiInfo() {

        return newApiInfoBuilder()

                .title("Spring Boot中使用Swagger2构建RESTfulAPIs")

                .description("更多SpringBoot相关文章请关注：http://blog.didispace.com/")

                .termsOfServiceUrl("http://blog.didispace.com/")

                .contact("程序猿DD")

                .version("1.0")

                .build();

   }

 

}

如上代码所示，通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。

再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

3.       启动Spring Boot程序

访问：http://localhost:8080/Swagger-ui.html。即可看到RESTful API的页面。可以再点开具体的API请求，以POST类型的/users请求为例，可找到上述代码中配置的Notes信息以及参数user的描述信息，如下图所示。

4.       API文档访问与调试

在上图请求的页面中，我们看到user的Value是个输入框？是的，Swagger除了查看接口功能外，还提供了调试测试功能，我们可以点击上图中右侧的Model Schema（黄色区域：它指明了User的数据结构），此时Value中就有了user对象的模板，我们只需要稍适修改，点击下方“Try it out！”按钮，即可完成了一次请求调用！

此时，你也可以通过几个GET请求来验证之前的POST请求是否正确。

相比为这些接口编写文档的工作，我们增加的配置内容是非常少而且精简的，对于原有代码的侵入也在忍受范围之内。因此，在构建RESTful API的同时，加入Swagger来对API文档进行管理，是个不错的选择。

2.3  Eureka注册中心集成Swagger

未集成Swagger时，当我们点击某个注册到Eureka Server上的某个服务的时候，链接的界面要么报404，要么就是空的，如下图所示：

在服务的配置文件中加上如下配置：

eureka.instance.status-page-url=http://localhost:${server.port}/swagger-ui.html

再次点击上述链接，可以看到2.2中所示的服务接口的信息描述。