新浦京81707con > 功能介绍 > API管理工具Swagger介绍及Springfox原理分析,swagge

原标题:API管理工具Swagger介绍及Springfox原理分析,swagge

浏览次数:99 时间:2020-02-07

swagger是贰个API框架,可以称作世界上最风靡的API工具。它提供了API管理的整整解决方案,举例API在线编辑器,API UI显示分界面,代码生成器等好些个功能。

浅谈springfox-swagger原理剖析与应用过程中遇到的坑,

swagger简介

swagger确实是个好东西,能够跟据业务代码自动生成相关的api接口文书档案,尤其用于restful风格中的项目,开采人士大约能够不要极其去维护rest api,那么些框架能够自动为你的作业代码生成restfut风格的api,何况还提供对应的测验分界面,自动展现json格式的响应。大大方便了后台开辟职员与前边一个的维系与联调花费。

springfox-swagger简介

签于swagger的兵不血刃功效,java开源界大牌spring框架飞速跟上,它充足利用自已的优势,把swagger集成到本身的类别里,整了二个spring-swagger,后来便衍变成springfox。springfox本身只是利用自个儿的aop的特点,通过plug的艺术把swagger集成了步入,它自身对事情api的变动,依旧依附swagger来完成。

至于这么些框架的文书档案,网络的资料非常少,大部分是入门级的粗略利用。本身在合龙那么些框架到温馨项指标进度中,碰着了大多坑,为理解决这几个坑,作者一定要扒开它的源码来看个终究。此文,就是记述本身在行使springfox进程中对springfox的生机勃勃部分知晓以至须求小心的地点。

springfox差不离原理

springfox的大约原理正是,在类型运行的过种中,spring上下文在伊始化的进度,框架自动跟据配置加载一些swagger相关的bean到当前的光景文中,并自行扫描系统中也许需求生成api文书档案这多少个类,并生成对应的音讯缓存起来。如若项目MVC调节层用的是springMvc那么会活动扫描全数Controller类,跟据那一个Controller类中的方法生成对应的api文书档案。

因本身的项目正是SpringMvc,所以此文就以Srping mvc集成springfox为例来钻探springfox的行使与原理。

SpringMvc集成springfox的步骤

率先,项目须要步向以下八个依据:

<!-- 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>

地点多少个依赖是项目集成springmvc及springfox最中心的重视,其余的依赖这里大概。此中第三个是springmvc的主导依据,第3个是swagger信任,第七个是界面相关的注重性,这么些不是必得的,就算你不想用springfox自带的api分界面包车型大巴话,也得以毫不那个,而除此以外本人写风流浪漫套符合本人项指标分界面。参预那多少个依赖后,系统后会自动步入一些跟springfox及swagger相关jar包,作者大致看了刹那间,首要有以下那样多少个:

springfox-swagger2-2.6.1.jar

swagger-annotations-1.5.10.jar

swagger-models-1.5.10.jar

springfox-spi-2.6.1.jar

springfox-core-2.6.1.jar

springfox-schema-2.6.1.jar

springfox-swagger-common-2.6.1.jar

springfox-spring-web-2.6.1.jar

guava-17.0.jar

spring-plugin-core-1.2.0.RELEASE.jar

spring-plug-metadata-1.2.0.RELEASE.jar

spring-swagger-ui-2.6.1.jar

jackson-databind-2.2.3.jar

jackson-annotations-2.2.3.jar

地点是自个儿透过目测以为springfox只怕需求的jar,可能未有完全例出springfox所需的保有jar。从上面jar能够看见pringfox除了依赖swagger之外,它还供给guava、spring-plug、jackson等信任包(注意jackson是用来生成json必需的jar包,假使项目里笔者并未参与那些依赖,为了集成swagger的话必须要附加再步入那些依赖)。

springfox的粗略利用

如若只用springfox的暗中认可的配置来讲,与springmvc集成起来特别轻松,只要写贰个相通于以下代码的类放到你的档期的顺序里就能够了,代码如下:

@Configuration

@EnableWebMvc

@EnableSwagger2

publicclass ApiConfig {}

小心到,上边是二个空的java类文件,类名能够专擅钦点,但必得到场上述类中标记的@Configuration、@EnableWebMvc、@EnableSwagger2多少个申明,这样就形成了springmvc与springfox的为主集成,有了多个注脚,项目运营后即可间接用挨近于以下的地址来查看api列表了:

那实乃贰个很奇妙的功力,轻易的八个评释,系统就自动展现出等级次序里全体Controller类的有着api了。以后,我们就那几个布局类出手,轻易解析它的原理。这一个类中绝非其余代码,很分明,八个评释起了重要的意义。此中@Configuration申明是spring框架中本身就有的,它是八个被@Component元注明标记的笺注,所以有了那个阐明后,spring会自动把那几个类实例化成二个bean注册到spring上下文中。第2个评释@EnableWebMvc故名思义,就是启用srpingmvc了,在Eclipse中式点心到这一个注明里面大约看一下,它正是因而元注脚@Import(DelegatingWebMvcConfiguration.class)往spring context中塞入了三个DelegatingWebMvcConfiguration类型的bean。小编想,那个类的指标应该就是为swagger提供了有的springmvc方面包车型大巴配备吧。第多少个注明:@EnableSwagger2,看名字应该能够想到,是用来集成swagger 2的,他通过元注明:@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();
 }
}

以此类底部通过一些评释,再引进SpringfoxWebMvcConfiguration类和SwaggerCommonConfiguration类,并通过ComponentScan表明,自动扫描springfox .swagger2相关的的bean到spring context中。这里,小编最感兴趣的是SpringfoxWebMvcConfiguration那几个类,那些类作者猜应该就是springfox集成mvc相比较基本的布局了,点步向,见到以下代码:

@Configuration
@Import({ModelsConfiguration.class })
@ComponentScan(basePackages = {
  "springfox.documentation.spring.web.scanners",
"springfox.documentation.spring.web.readers.operation","springfox.documentation.spring.web.readers.parameter","springfox.documentation.spring.web.plugins","springfox.documentation.spring.web.paths"
})

@EnablePluginRegistries({ DocumentationPlugin.class,
  ApiListingBuilderPlugin.class,
  OperationBuilderPlugin.class,
  ParameterBuilderPlugin.class,
  ExpandedParameterBuilderPlugin.class,
  ResourceGroupingStrategy.class,
  OperationModelsProviderPlugin.class,
  DefaultsProviderPlugin.class,
  PathDecorator.class
})
publicclassSpringfoxWebMvcConfiguration {}

其意气风发类中上面包车型地铁代码,无非便是通过@Bean注明再投入一些新的Bean,作者对它的兴趣不是相当大,笔者最感兴趣的是尾部通过@EnablePluginRegistries加入的那个东西。springfox是依赖spring-plug的编写制定结合swagger的,spring-plug具体是怎么贯彻的,笔者一时半刻还从寅时间去研讨spring-plug的规律。但在下文少禽提到自身写一个plug插件来扩大swagger的意义。上面通过@EnablePluginRegistries参预的plug中,还尚无时间去看它全体的代码,最近自己看过的代码重要有ApiListingBuilderPlugin.class, OperationBuilderPlugin.class,ParameterBuilderPlugin.class, ExpandedParameterBuilderPlugin.class,

率先个ApiListingBuilderPlugin,它有四个完毕类,分别是ApiListingReader和SwaggerApiListingReader。个中ApiListingReader会自动跟据Controller类型生成api列表,而SwaggerApiListingReader会跟占领@Api注脚标志的类生成api列表。OperationBuilderPlugin插件正是用来生成现实api文书档案的,那个类型的插件,有成都百货上千浩大贯彻类,他们分别分工,各做各的事体,具体我从没稳重去看,只关怀了当中叁个兑现类:OperationParameter里德r,那一个类是用以读取api参数的Plugin。它依据于ModelAttributeParameterExpander工具类,能够将Controller中接口方法参数中国和欧洲大致类型的指令对像自动深入分析它当中的天性得出富含全体属性的参数列表(这里存在一个只怕晤面世不过递归的坑,下文有介绍)。而ExpandedParameterBuilderPlugin插件,主如若用以扩展接口参数的部分功效,比如决断这么些参数的数据类型以致是不是为那个接口的必须参数等等。总体上说,整个springfox-swagger内部其实是由那后生可畏多元的plug转运起来的。他们在系统运维时,就被调起来,有个别用来围观出接口列表,有个别用来读取接口参数等等。他们联合的目地正是把系统中持有api接口都围观出来,并缓存起来供顾客查看。那么,这大器晚成多重表plug到底是怎么样被调起来的,它们的推行入口倒底在哪?

   大家把注意点放到上文SpringfoxWebMvcConfiguration那个类代码底部的ComponentScan注脚内容上来,那大器晚成段申明中围观了三个叫springfox.documentation.spring.web.plugins的package,这几个package在springfox-spring-web-2.6.1.jar中能够找到。那些package下,大家开掘存八个一点都不小旨的类,那正是DocumentationPluginsManager和DocumentationPluginsBootstrapper。对于第二个DocumentationPluginsManager,它是四个未曾贯彻任何接口的bean,但它里面有成都百货上千PluginRegistry类型的属性,何况都以透过@Autowired注脚把属性值注入进来的。接合它的类名来看,相当轻便想到,那些就是治本全体plug的贰个微电脑了。很好驾驭,因为ComponentScan表明的配备,全体的plug实例都会被spring实例化成贰个bean,然后被注入到那个DocumentationPluginsManager实例中被合併保管起来。在这里个package中的另三个根本的类DocumentationPluginsBootstrapper,看名字就能够猜到,他或然正是plug的运行类了。点进去看具体时就足以开掘,他果然是三个被@Component标记了的零器件,何况它的布局方法中注入了正要描述的DocumentationPluginsManager实例,何况最关键的,它还落到实处了SmartLifecycle接口。对spring bean生命周期有所明白的人的都了然,这些组件在被实例化为叁个bean归入srping context中被管制起来的时候,会自动调用它的start(State of Qatar方法。点到start(State of Qatar中看代码时就能意识,它有少年老成行代码scanDocumentation(buildContext(each卡塔尔国卡塔尔;正是用来扫描api文书档案的。进一层追踪这些措施的代码,就足以开掘,那个艺术最终会透过它的DocumentationPluginsManager属性把具有plug调起一同扫描整个种类并生成api文书档案。扫描的结果,缓存在DocumentationCache那几个类的叁个map属性中。

   以上正是,srpingMvc整合springfox的差不离原理。它根本是经过EnableSwagger2评释,向srping context注入了一三种bean,并在系统运维的时候自动扫描系统的Controller类,生成对应的api新闻并缓存起来。别的,它还注入了部分被@Controller注脚标志的Controller类,作为ui模块访谈api列表的进口。举个例子springfox-swagger2-2.6.1.jar包中的Swagger2Controller类。那一个Controller正是ui模块中用来寻访api列表的分界面地址。在拜访

刺探了springfox的规律,上边来拜望springfox使用进度中,作者蒙受的哪些坑。

springfox第风流倜傥深水湾:配置类生成的bean必需与spring mvc共用同八个上下文。

前文描述了,在springmvc项目中,集成springfox是只要在档案的次序写三个之类的未有其他事情代码的简约布署类就足以了。

@Configuration
@EnableWebMvc
@EnableSwagger2
publicclass ApiConfig {
}

因为@Configuration表明的魔法,spring会自动把它实例化成三个bean注入到上下文。但切记要专心的三个坑就是:这几个bean所在的上下文必得跟spring mvc为同三个上下文。怎么解理呢?因为在骨子里的spring mvc项目中,经常有八个上下文,三个是跟上下文,另叁个是spring mvc(它是跟上下文的子上下文)。当中跟上下文是就是web.xml文件中跟spring相关的老大org.springframework.web.context.request.RequestContextListener监听器,加载起来的上下文,经常大家会写二个叫spring-contet.xml的配置文件,这在那之中的bean最终会最早化到跟上下文中,它根本不外乎系统里面包车型客车service,dao等bean,也包涵数据源、事物等等。而另三个上下文是便是spring mvc了,它经过web.xml中跟spring mvc相关的非常org.springframework.web.servlet.DispatcherServlet加载起来,他普通有多个配置文件叫spring-mvc.xml。我们在写ApiConfig那一个类时,如决料定用@Configuration申明来加载,那么就亟须确定保证那个类所在的门路正幸好springmvc的component-scan的安插的base-package范围内。因为在ApiConfig在被spring加载时,会注入一列连串的bean,而那一个bean中,为了能自动扫描出装有Controller类,有个别bean要求依赖于SpringMvc中的一些bean,假使项目把Srpingmvc的上下文与跟上下文分开来,作为跟上下文的子上下文的话。假设不当心让那一个ApiConfig类型的bean被跟上文加载到,因为root context中尚无spring mvc的context中的那二个配置类时就能够报错。

现实上,笔者并不赞成通过@Configuration表明来布局Swagger,因为作者感到,Swagger的api功效对于临盆类型来讲是卑不足道的。我们Swagger往往是用来测验境况供项前段时间端团队开垦或供其余系统作接口集成使上。系统上线后,很恐怕在生育连串上隐蔽这么些api列表。 但倘使安插是透过@Configuration申明写死在java代码里的话,那么上线的时候想去掉那一个效应的时候,那就窘迫了,一定要改过java代码重新编写翻译。基于此,我推荐的叁个主意,通过spring最守旧的xml文件配置方式。具体做法便是去掉@Configuration申明,然后它写四个贴近于<bean class="com.jad.web.mvc.swagger.conf.ApiConfig"/>那样的bean配置到spring的xml配置文件中。在root context与mvc的context分开的门类中,直接配备到spring-mvc.xml中,那样就确定保证了它跟springmvc 的context一定处于同贰个context中。

springfox第二北角:Controller类的参数,注意幸免现身Infiniti递归的意况。

Spring mvc有无往不克的参数绑定机制,能够自行把供给参数绑定为三个自定义的命令对像。所以,相当多开垦职员在写Controller时,为了偷懒,直接把三个实体对像作为Controller方法的七个参数。例如上面这几个示例代码:

@RequestMapping(value = "update")
public String update(MenuVomenuVo, Model model){
}

那是绝大大多技师中意在Controller中写的退换有些实体的代码。在跟swagger集成的时候,这里有七个马湾岛。借使MenuVo那么些类中颇负的特性都是大旨类型,那幸而,不会出什么样难点。但假设这几个类里面有部分别的的自定义类型的性质,何况以此特性又径直或直接的留存它自个儿类型的性情,那就能够出标题。比方:要是MenuVo这些类是菜单类,在此个类时又满含MenuVo类型的叁性子质parent代表它的父级菜单。那样的话,系统运营时swagger模块就因不能加载那个api而直白报错。报错的原因就算,在加载那么些方式的经过中会拆解深入分析那个update方法的参数,开掘参数MenuVo不是轻巧类型,则会自行以递归的点子疏解它富有的类属性。那样就比较轻便陷于极其递归的死循环。

为精通决这一个难题,小编最近只是本人写了二个OperationParameterReader插件实现类以至它依赖的ModelAttributeParameterExpander工具类,通过配备的不二诀窍替换掉到srpingfox原本的这三个类,眉来眼去般的把参数深入剖判那几个逻辑替换掉,并逃脱Infiniti递归。当然,这一定于是风度翩翩种修正源码级其余办法。作者日前还尚无找到毁灭那些题材的更完备的点子,所以,只好提出大家在用spring-fox Swagger的时候尽量防止这种特别递归的情状。终归,那不适合springmvc命令对像的专门的学业,springmvc参数的一声令下对像中最棒只含有轻便的中坚项目属性。

springfox第三大小磨刀:api分组相关,Docket实例不能顺延加载

springfox暗中认可会把持有api分成大器晚成组,这样经过相同于:

@EnableWebMvc
@EnableSwagger2
publicclass ApiConfig {
@Bean
 public Docket customDocket() {
    return newDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
  }
}

上述代码中经过@Bean注入叁个Docket,那一个结构实际不是必得的,若无那个构造,框架会自身生成八个暗许的Docket实例。那个Docket实例的效劳正是钦点全数它能管住的api的公共信息,例如api版本、小编等等基本音讯,以致内定只列出什么样api(通过api地址或注脚过滤)。

Docket实例能够有多个,举个例子如下代码:

@EnableWebMvc
@EnableSwagger2
publicclass ApiConfig {
@Bean
 public Docket customDocket1() {
    return newDocket(DocumentationType.SWAGGER_2)
.groupName("apiGroup1").apiInfo(apiInfo()).select()

.paths(PathSelectors.ant("/sys/**"));

  }

@Bean
 public Docket customDocket2() {
    return newDocket(DocumentationType.SWAGGER_2)
.groupName("apiGroup2").apiInfo(apiInfo())
.select()
.paths(PathSelectors.ant("/shop/**"));
  }
}

当在品种中安插了多少个Docket实例时,也就足以对api进行分组了,比方上面代码将api分为了两组。在这里种情景下,必得给每风姿罗曼蒂克组指定一个差别的名目,举个例子上边代码中的"apiGroup1"和"apiGroup2",每后生可畏组能够用paths通过ant风格之处表明式来钦赐哪后生可畏组管理哪些api。比方上边配置中,第意气风发组管理地方为/sys/起始的api第二组管理/shop/最初的api。当然,还会有好些个任何的过滤方式,比方跟据类证明、方法注解、地址正则表达式等等。分组后,在api 列表界面右上角的下拉筛选中就足以筛选区别的api组。那样就把项目标api列表分散到不一样的页面了。那样,即方便管理,又不致于页面因须求加载太多api而假死。

然而,同使用@Configuration同样,小编并差异情采取@Bean来安排Docket实例给api分组。因为这么,肖似会把代码写死。所以,我引入在xml文件中友好布置Docket实例实现这一个相仿的功能。当然,考虑到Docket中的众多质量,直接配备bean相比艰苦,能够和睦为Docket写三个FactoryBean,然后在xml文件中布署FactoryBean就能够了。不过将Docket配置到xml中时。又会曰镪一个笔架山,就那是,spring对bean的加载形式暗中认可是延迟加载的,在xml中央直属机关接配置那几个Docket实例Bean后。你会开掘,未有点效应,页面左上角的下拉列表中跟本未有你的分组项。

那么些主题材料曾干扰过自家多数少个钟头,后来凭经验预计出恐怕是因为sping bean暗中认可延迟加载,那么些Docket实例还未加载到spring context中。实事证明,小编的估摸是没错。小编不知底那究竟springfox的叁个bug,依旧因为作者跟本不应当把对Docket的安顿从原来的java代码中搬到xml配置文件中来。

springfox其余的坑:springfox还只怕有个别此外的坑,比如@ApiOperation评释中,假诺不钦点httpMethod属性具体为有些get或post方法时,api列表中,会它get,post,delete,put等全体办法都列出来,搞到api列表重复的太多,很无耻。此外,还大概有在测验时,遭逢登入权限难点,等等。这一群堆的比比较容易于化解的小坑,因为篇幅有限,笔者就非常少说了。还会有诸如@Api、@ApiOperation及@ApiParam等等证明的用法,网络海人民广播广播台大那地点的文档,我就不重复了。

如上正是本文的全体内容,希望对我们的求学抱有利于,也指望我们多都赐教帮客之家。

swagger简单介绍swagger确实是个好东西,能够跟据业务代码自动生成相关的api接口文书档案,越发...

随着前后端的抽离,借口文书档案变的愈发珍视,springfox是透过表明的样式自动生成API文书档案,利用它,能够很有益于的书写restful API,swagger首要用于展现springfox生成的API文书档案。

生机勃勃旦想引入swagger举行API处理。近年来 springfox 是二个很好的选拔,它里面会活动解析Spring容器中Controller暴表露的接口,并且也提供了三个分界面用于展现或调用这个API。下图就是总结的叁个行使springfox的API展现分界面。

官方网址地址:

图片 1

Springfox差不离原理

springfox的前身是swagger-springmvc,用于springmvc与swagger的重新组合。

springfox的大致原理正是,在项目运营的过种中,spring上下文在开始化的历程,框架自动跟据配置加载一些swagger相关的bean到当下的前后文中,并自动扫描系统中可能供给生成api文书档案那么些类,并生成对应的消息缓存起来。假若项目MVC调整层用的是springMvc那么会活动扫描全数Controller类,跟据这几个Controller类中的方法生成对应的api文书档案。

如果在springboot项目中应用springfox,要求3个步骤:

Spring集成Springfox步骤及评释:

1、maven添加springfox依赖

一、添加Swagger2依赖

2、运营类拉长@EnableSwagger2注明

    <!-- Swagger -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.6.1</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.6.1</version>
    </dependency>

3、结构Docket bean用于显示API

二、application.properties中增多配置

布局完事后踏入 就能够查看controller中的接口音信,并根据Docket中构造的规规矩矩举办展示。

#解决中文乱码问题
banner.charset=UTF-8
server.tomcat.uri-encoding=UTF-8
spring.http.encoding.charset=UTF-8
spring.http.encoding.enabled=true
spring.http.encoding.force=true
spring.messages.encoding=UTF-8

#Swagger Configure Properties
sop.swagger.enable=true
sop.swagger.packageScan=com.example
sop.swagger.title=UserController Restfull API
sop.swagger.description=UserController Restfull API
sop.swagger.version=3.0

在拆解深入分析springfox完毕原理早先,首先看下springfox对文书档案Documentation的概念:

三、成立SwaggerConfigProperties加载配置项

图片 2

package com.example.config;

import java.io.Serializable;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@ConfigurationProperties(prefix = "sop.swagger")
@Component
public class SwaggerConfigProperties implements Serializable {
    /**
     * 是否开启Swagger
     */
    private boolean enable = false;
    /**
     * 要扫描的包
     */
    private String packageScan;
    /**
     * 标题
     */
    private String title;
    /**
     * 描述
     */
    private String description;
    /**
     * 版本信息
     */
    private String version;

    public boolean isEnable() {
        return enable;
    }

    public void setEnable(boolean enable) {
        this.enable = enable;
    }

    public String getPackageScan() {
        return packageScan;
    }

    public void setPackageScan(String packageScan) {
        this.packageScan = packageScan;
    }

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    public String getVersion() {
        return version;
    }

    public void setVersion(String version) {
        this.version = version;
    }
}

文书档案Documentation定义得很清晰,重要由groupName、basePath(context帕特h卡塔尔(قطر‎、apiListings、resourceListing等属性组成。

四、创建Swagger2配置类

里头API列表被封装成ApiListing。ApiListing中又怀有ApiDesciption集结援用,各个ApiDesciption都怀有二个API集结的引用,Operation也正是切实可行的接口操作,内部含有了该接口对应的http方法、produces、consumes、契约、参数集、响应音信集等重重成分。

package com.example.config;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2 {
    @Autowired
    private SwaggerConfigProperties scp;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.web"))
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()
            .title(scp.getTitle())
            .description(scp.getDescription())
            .version("1.0")
            .build();
    }
}

springfox通过spring-plugin的主意将Plugin注册到Spring上下文中,然后使用这几个plugin实行API的围观职业,这里的围观职业实际也正是构造Documentation的干活,把围观出的结果封装成Documentation并归入到DocumentationCache内部存款和储蓄器缓存中,之后swagger-ui分界面展现的API音讯经过Swagger2Controller暴光,Swagger2Controller内部直接从DocumentationCache中查找Documentation。

五、创建model

下图正是部分Plugin具体协会对应的文书档案音讯:

package com.example.model;

import io.swagger.annotations.ApiModelProperty;

public class User {
    @ApiModelProperty(value = "主键")
    private Long id;
    @ApiModelProperty(value = "名字")
    private String name;
    @ApiModelProperty(value = "年龄")
    private Integer age;
    @ApiModelProperty(value = "密码")
    private String password;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    @Override
    public String toString() {
        return "User{"  
            "id="   id  
            ", name='"   name   '''  
            ", age="   age  
            ", password="   password  
            '}';
    }
}

图片 3

六、创建Controller

代码细节方面包车型地铁剖释:

package com.example.web;

import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

import com.example.model.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;

@RestController
@Api("userController相关api")
public class UserController {
    @ApiOperation("获取用户信息")
    @ApiImplicitParams({
        @ApiImplicitParam(paramType = "header", name = "username", dataType = "String", required = true,
            value = "用户的姓名", defaultValue = "xiaoqiang"),
        @ApiImplicitParam(paramType = "query", name = "password", dataType = "String", required = true, value = "用户的密码",
            defaultValue = "xiaoxiong")
    })
    @ApiResponses({
        @ApiResponse(code = 400, message = "请求参数没填好"),
        @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    })
    @RequestMapping(value = "/getUser", method = RequestMethod.GET)
    public User getUser(@RequestHeader("username") String username, @RequestParam("password") String password) {
        User user = new User();
        user.setName(username);
        user.setPassword(password);
        return user;
    }

    @ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    @RequestMapping(value = "", method = RequestMethod.POST)
    public String postUser(@RequestBody User user) {
        Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());
        users.put(user.getId(), user);
        return "success";
    }

    @ApiIgnore
    @RequestMapping(value = "/", method = RequestMethod.GET)
    public String home() {
        return "hello";
    }
}

很醒目,入口处在@EnableSwagger2表明上,该注脚会import叁个结构类Swagger2DocumentationConfiguration。

做到上述代码增添上,运维Spring Boot程序,访谈:
。就会来看前文所展现的RESTful API的页面。大家能够再点开具体的API央求,以POST类型的/users诉求为例,可找到上述代码中我们配备的Notes音讯以至参数user的陈述消息,如下图所示。

Swagger2DocumentationConfiguration做的事情:

图片 4

1、布局Bean。比如HandlerMapping,HandlerMapping是springmvc中用于拍卖央浼与handler(controller中的方法卡塔尔国之间映射关系的接口,springboot中暗许使用的HandlerMapping是RequestMappingHandlerMapping,Swagger2DocumentationConfiguration配置类里组织的是PropertySourcedRequestMappingHandlerMapping,该类世襲RequestMappingHandlerMapping。

七、API文书档案访问与调治

2、import别的配置类,例如SpringfoxWebMvcConfiguration、SwaggerCommonConfiguration

在上海体育地方伏乞的页面中,我们看见user的Value是个输入框?是的,Swagger除了查看接口作用外,还提供了调度测量试验效用,我们能够点击上海体育地方中右边的Model Schema(茄皮紫区域:它指明了User的数据构造),那个时候Value中就有了user对象的模版,大家只需求稍适改过,点击下方“Try it out!”按键,就可以成功了二回倡议调用!

本文由新浦京81707con发布于功能介绍,转载请注明出处:API管理工具Swagger介绍及Springfox原理分析,swagge

关键词: 新浦京81707con 原理 api 管理工具 SpringBoot

上一篇:解决数据科学一公里问题,Cloud和Docker构建微服务

下一篇:没有了