基于SpringCloud的Microservices架构实战案例-在线API管理

simplemall项目前几篇回顾:

源码地址:https://github.com/backkoms/simplemall

前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API文档的框架。 本实战案例中也引入swagger2作为API管理工具,下面罗列下swagger2+SpringBoot使用步骤。

SpringBoot集成Swagger2

第一步,pom配置

  1. <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->

  2. <dependency>

  3.    <groupId>io.springfox</groupId>

  4.    <artifactId>springfox-swagger2</artifactId>

  5.    <version>2.6.1</version>

  6. </dependency>

  7. <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->

  8. <dependency>

  9.    <groupId>io.springfox</groupId>

  10.    <artifactId>springfox-swagger-ui</artifactId>

  11.    <version>2.6.1</version>

  12. </dependency>

第二步编写配置管理类Swagger2Config

  1. package com.simplemall.micro.serv.page;

  2. import org.springframework.context.annotation.Bean;

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

  4. import io.swagger.annotations.ApiOperation;

  5. import springfox.documentation.builders.ApiInfoBuilder;

  6. import springfox.documentation.builders.PathSelectors;

  7. import springfox.documentation.builders.RequestHandlerSelectors;

  8. import springfox.documentation.service.ApiInfo;

  9. import springfox.documentation.spi.DocumentationType;

  10. import springfox.documentation.spring.web.plugins.Docket;

  11. import springfox.documentation.swagger2.annotations.EnableSwagger2;

  12. /**

  13. * swagger2 configuration

  14. *

  15. * @author guooo

  16. *

  17. */

  18. @Configuration//SpringBoot启动时自动装载

  19. @EnableSwagger2//打开swagger2功能,缺失的话同样无法打开ui页面

  20. publicclassSwagger2Config{

  21.    @Bean

  22.    publicDocket createRestApi(){

  23.        returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()

  24.                .apis(RequestHandlerSelectors.basePackage("com.simplemall.micro.serv.page.api"))

  25.                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

  26.                .paths(PathSelectors.any())

  27.                .build();

  28.    }

  29.    privateApiInfo apiInfo(){

  30.        returnnewApiInfoBuilder().title("Front app Swagger apis").description("For micro-service 's app to use")

  31.                .version("V1.0").build();

  32.    }

  33. }

经过以上两步简单的配置后,可以直接进行接口代码的编写。

  1. @Api(value ="用户服务", tags ="用户服务接口")

  2. @RestController

  3. @RefreshScope// 使用该注解的类,会在接到SpringCloud配置中心配置刷新的时候,自动将新的配置更新到该类对应的字段中。需要重新触发加载动作可以使用POST方式请求/refresh接口,该接口位于spring-boot-starter-actuator依赖,调用前需添加否则404。

  4. publicclassAPIAccountController{

  5.    @ApiOperation(value ="用户登陆")

  6.    @RequestMapping(value ="acc/login", method ={RequestMethod.POST })

  7.    publicRestAPIResult<String> login(@ApiParam(value ="手机号")@RequestParam(required =true)String phone,

  8.            @ApiParam(value ="密码")@RequestParam(required =true)String password,HttpSession session){

  9.        RestAPIResult<String> restAPIResult =newRestAPIResult<>();

  10.        Account account = accountFeignClient.login(phone, password);

  11.    }

使用swagger进行API管理的话,对代码有一定的侵入性,这个需要考虑在内。之前也提到过几种在线API的管理方式,点击链接《介绍几款常用的在线API管理工具

使用SpringBoot技术,再以maven原始的方式引入swagger使用的话,远不如一个starter来的爽,这里介绍一个swagger-starter,可以更快捷的与spring boot集成使用。

swagger-spring-boot-starter应用

在pom.xml中引入依赖:【当前最新版本 1.7.0.RELEASE】

  1. <dependency>

  2.    <groupId>com.spring4all</groupId>

  3.    <artifactId>swagger-spring-boot-starter</artifactId>

  4.    <version>1.7.0.RELEASE</version>

  5. </dependency>

注意:从1.6.0开始,我们按Spring Boot官方建议修改了artifactId为swagger-spring-boot-starter,1.6.0之前的版本不做修改,依然为使用spring-boot-starter-swagger !

在应用主类中增加@EnableSwagger2Doc注解

  1. @EnableSwagger2Doc

  2. @SpringBootApplication

  3. publicclassBootstrap{

  4.    publicstaticvoid main(String[] args){

  5.        SpringApplication.run(Bootstrap.class, args);

  6.    }

  7. }

默认情况下就能产生所有当前Spring MVC加载的请求映射文档。

参数配置,配置示例

  1. swagger.enabled=true

  2. swagger.title=spring-boot-starter-swagger

  3. swagger.description=Starterfor swagger 2.x

  4. swagger.version=1.4.0.RELEASE

  5. swagger.license=ApacheLicense,Version2.0

  6. swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html

  7. swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger

  8. swagger.contact.name=didi

  9. swagger.contact.url=http://blog.didispace.com

  10. [email protected]

  11. swagger.base-package=com.didispace

  12. swagger.base-path=/**

  13. swagger.exclude-path=/error, /ops/**

  14. swagger.globalOperationParameters[0].name=name one

  15. swagger.globalOperationParameters[0].description=some description one

  16. swagger.globalOperationParameters[0].modelRef=string

  17. swagger.globalOperationParameters[0].parameterType=header

  18. swagger.globalOperationParameters[0].required=true

  19. swagger.globalOperationParameters[1].name=name two

  20. swagger.globalOperationParameters[1].description=some description two

  21. swagger.globalOperationParameters[1].modelRef=string

  22. swagger.globalOperationParameters[1].parameterType=body

  23. swagger.globalOperationParameters[1].required=false

  24. // 取消使用默认预定义的响应消息,并使用自定义响应消息

  25. swagger.apply-default-response-messages=false

  26. swagger.global-response-message.get[0].code=401

  27. swagger.global-response-message.get[0].message=401get

  28. swagger.global-response-message.get[1].code=500

  29. swagger.global-response-message.get[1].message=500get

  30. swagger.global-response-message.get[1].modelRef=ERROR

  31. swagger.global-response-message.post[0].code=500

  32. swagger.global-response-message.post[0].message=500post

  33. swagger.global-response-message.post[0].modelRef=ERROR

详细介绍可参考源码,地址:https://github.com/SpringForAll/spring-boot-starter-swagger。由于JDK代码编译版本的限制,JDK1.7是不支持的,可使用1.8

基于SpringCloud的Microservices架构实战案例-在线API管理

扩展阅读:

基于SpringCloud的Microservices架构实战案例-在线API管理
 

相关推荐