Swagger使用总结

Swagger使用总结https://www.cnblogs.com/h9527/p/5506956.html

1. Swagger是什么？

官方说法：Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

个人觉得，swagger的一个最大的优点是能实时同步api与文档。在项目开发过程中，发生过多次：修改代码但是没有更新文档，前端还是按照老旧的文档进行开发，在联调过程中才发现问题的情况（当然依据开闭原则，对接口的修改是不允许的，但是在项目不稳定阶段，这种情况很难避免）。

2. spring boot 集成 Swagger

目前维护的系统是基于springboot框架开发的，因此本文会详细描述springboot与swagger集成的过程。

spring-boot系统集成swagger需要进行如下操作：

  1. 添加maven依赖，需要在系统的pom中添加如下依赖：

    gradle:compile('io.springfox:springfox-swagger2:2.2.2')
     <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
 </dependency>

  2. 添加swagger配置文件，配置文件如下：

  3. import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;

    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;

    @Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()  // 选择那些路径和api会生成document
                .apis(RequestHandlerSelectors.any()) // 对所有api进行监控
                .paths(PathSelectors.any()) // 对所有路径进行监控
                .build();
    }

}

    通过注解EnableSwagger2声明Swagger的可用性，此处会定义一个类型为Docket的bean，
    关于docket类的说明如下：

    A builder which is intended to be the primary interface into the swagger-springmvc framework.Provides sensible defaults and convenience methods for configuration.

    Docket的select()方法会提供给swagger-springmvc framework的一个默认构造器（ApiSelectorBuilder），这个构造器为配置swagger提供了一系列的默认属性和便利方法。

  4. 测试

    通过访问：http://localhost:8080/your-app-root/v2/api-docs ，能测试生成的api是否可用。此时返回的是一个json形式的页面，可读性不好。可以通过Swagger UI来生成一个可读性良好的api页面。具体做法就是，在pom中添加相关依赖。如下：

    <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
</dependency>
  5.   gradle:  compile('io.springfox:springfox-swagger-ui:2.2.2')

  6. 再次访问：http://localhost:8080/your-app-root/swagger-ui.html 就可以看到可读性较好的api文档页面。

  7. 注意：

    1. http://localhost:8080/your-app-root/v2/api-docs 中your-app-root指的你的wabapp的根路径，我目前的webapp就默认在根路径下，所以地址是：http://localhost:8080/v2/api-docs
    2. spring-mvc上引用swagger需要做其他相关的配置，具体请查看参考文献
    3. swagger对restful风格的api支持的比较好，非restful风格的api支持的不是很好，对于非restful风格的api或者其他语言（非java语言）可以采用 http://editor.swagger 编辑器来收工完成相关的API编写

    4. SpringBoot 配置SwaggerUI 访问404的小坑。

      在学习SpringBoot构建Restful API的时候遇到了一个小坑，配置Swagger UI的时候无法访问。

      首先在自己的pom文件中加入Swagger的依赖，如下所示：

      ?
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
          </dependency>
       
          <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
      </dependency>

      然后在新建一个SwaggerConfig类：

      ?
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      Configuration
      @EnableSwagger2
      public class SwaggerConfig {
        @Bean
        public Docket createRestApi() {
          return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(apiInfo())
              .select()
              .apis(RequestHandlerSelectors.basePackage("com.nightowl"))
              .paths(PathSelectors.any())
              .build();
        }
        private ApiInfo apiInfo() {
          return new ApiInfoBuilder()
              .title("NightOwl RESTful APIs")
              .description("关注我 http://hwangfantasy.github.io/")
              .termsOfServiceUrl("http://hwangfantasy.github.io/")
              .contact("颜艺学长")
              .version("1.0")
              .build();
        }
      }

      最后在自己的Controller中加上一系列的API注解即可，其实不需要加上API注解也可以正常使用。 
      最后在localhost:8080/swagger-ui.html 访问即可看到swagger页面了。

      但是关键来了，我第一次按照这样的方法配置却提示如下错误：

      ?
      1
      2
      3
      4
      5
      6
      7
      Whitelabel Error Page
       
      This application has no explicit mapping for /error, so you are seeing this as a fallback.
       
      Thu Nov 24 19:57:13 CST 2016
      There was an unexpected error (type=Not Found, status=404).
      No message available

      但是我新建一个项目重新配置却没有任何问题，于是想到自己的项目中肯定有哪些配置与swagger冲突了， 
      最后发现在 application.properties 中把

      ?
      1
      spring.resources.static-locations=classpath:/static/

      这一行注释掉即可访问了。

      以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持脚本之家。

      您可能感兴趣的文章:

       

      原文链接：http://blog.csdn.net/hwangfantasy/article/details/66542602

参考文献

  1. swagger-2-documentation-for-spring-rest-api
posted @ 2018-06-15 14:28  董永辉Bruno  阅读(10449)  评论(0)    收藏  举报