与Swagger集成的三种方式

版权声明:本文为博主原创文章,未经博主允许不得转载。 https://blog.csdn.net/u010924834/article/details/77427530

背景

  客户在使用REST接口来获取数据,比如要根据group的名字来获取group的所有信息。假如是一个这样的REST API:/groups/groupname。但是用户的groupname中包含slash(“/”),URL就变成/groups/groupname/groupname这样的形式。我们知道,多了一个slash之后,REST就会认为这是另外的资源,所以对于用户的请求,是没有对应的资源返回给用户的(后台是没有对应的方法接收请求)。对于这个问题的解决思路和多种解决办法,在这篇文章中不会详述,我只是说我采用的办法。增加一个新的API:/groups/**,这个新的API可以接收用户请求中包含slash这种情况。

  因为项目中的所有RESTAPI都使用SwaggerUI展示了出来,当我增加了这个新的API之后,它也出现在了SwaggerUI上面,而我不想把这个API暴露给用户,我该怎么办呢?

  上网查了很多资料,发现一些解决办法,比如在注解中将hidden设置为true,或者在什么pathSelector中配置你不想显示的url……当我在项目中试的时候,发现解决办法中的注解来自不同的包;即便项目中有相同的注解,我的项目中该注解却没有hidden属性(版本问题);或者是要修改的配置类中的方法在我项目中根本就没有。Make me confused!怎么和swagger相关的有这么多不同的包。所以针对我在查询过程遇到的几种包查了查区别,终于对他们的关系和各自的实现方式有了个清晰的看法。

  • difference between springfox and com.mangofactory
  • ways of integrating swagger and spring

导读

  本篇文章分为三个部分,第一部分介绍我理解的Swagger UI;第二部分由不同的包引出与Swagger UI集成的不同方式。第三部分给出实践性的Demo,放在下一篇文章里叙述。

什么是Swagger

  • Swagger是将你写的接口文档化的工具。
  • Swagger UI能将项目的接口以UI的形式展现出来,并可以在此UI上查看各个接口的定义,并可以直接使用此接口访问数据。Swagger UI是Swagger的一部分。

这里写图片描述

(以上是用自己的话理解的,更准确的解释请看下图)

这里写图片描述

与Swagger集成三种方式

Here is an explanation of the different libraries.

Springfox is in a sense v2 of the swagger library that used to be packaged as mangofactory. What happened was we transitioned from using a private repo to creating a github organization so support development as a team.
(Springfox是swagger库的v2版本,之前都打包成mangofactory。把库升级为spingfox是为了将原有的私有库转变成github组织以支持团队开发。)

In short mangofactory evolved into springfox which supports 2.0 version of swagger spec (in addition to 1.2). To be clear springfox and its predecessor supports spring mvc.
(mangofactory发展成了springfox,从而支持swagger的2.0规范(1.2除外),springfox和mangofactory都支持springmvc。)

io.swagger is the mother ship if you will. It has great support for spring and jax-rs. So if you’re looking for support for Jax-rs based services using spring or otherwise that’s a great option.
(io.swagger主要来支持spring和jax-rs,jax-rs是J2EE对RESTful API的支持,比如你项目中使用了spring,jax-rs,没用springmvc,可以使用这个包与swagger集成。)

参考:https://stackoverflow.com/questions/35835081/spring-swagger-ui-what-is-difference-between-io-swagger-io-springfox-and-com

总结

  如果你的项目使用jax-rs来实现RESTful接口,你就用io.swagger来集成swagger;如果你的项目使用springmvc来实现RESTful接口,最新的方法还是推荐使用springfox,但是也存在还在继续使用mangofactory来实现与swagger集成的项目。

  下面的链接给出了不同方式的大体实现方式,大家可以参考一下,并相应的去github上找一些demo来了解具体实现。
  
  https://stackoverflow.com/questions/26720090/a-simple-way-to-implement-swagger-in-a-spring-mvc-application

阅读更多

没有更多推荐了,返回首页