simplemall项目前几篇回顾：
源码地址：https://github.com/backkoms/simplemall
前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。 本实战案例中也引入swagger2作为API管理工具，下面罗列下swagger2+SpringBoot使用步骤。
SpringBoot集成Swagger2
第一步，pom配置
-
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> -
<dependency> -
<groupId>io.springfox</groupId> -
<artifactId>springfox-swagger2</artifactId> -
<version>2.6.1</version> -
</dependency> -
-
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> -
<dependency> -
<groupId>io.springfox</groupId> -
<artifactId>springfox-swagger-ui</artifactId> -
<version>2.6.1</version> -
</dependency>
第二步编写配置管理类Swagger2Config
-
package com.simplemall.micro.serv.page; -
-
import org.springframework.context.annotation.Bean; -
import org.springframework.context.annotation.Configuration; -
-
import io.swagger.annotations.ApiOperation; -
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; -
-
/** -
* swagger2 configuration -
* -
* @author guooo -
* -
*/ -
@Configuration//SpringBoot启动时自动装载 -
@EnableSwagger2//打开swagger2功能，缺失的话同样无法打开ui页面 -
publicclassSwagger2Config{ -
-
@Bean -
publicDocket createRestApi(){ -
returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() -
.apis(RequestHandlerSelectors.basePackage("com.simplemall.micro.serv.page.api")) -
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) -
.paths(PathSelectors.any()) -
.build(); -
} -
-
privateApiInfo apiInfo(){ -
returnnewApiInfoBuilder().title("Front app Swagger apis").description("For micro-service 's app to use") -
.version("V1.0").build(); -
} -
}
经过以上两步简单的配置后，可以直接进行接口代码的编写。
-
@Api(value ="用户服务", tags ="用户服务接口") -
@RestController -
@RefreshScope// 使用该注解的类，会在接到SpringCloud配置中心配置刷新的时候，自动将新的配置更新到该类对应的字段中。需要重新触发加载动作可以使用POST方式请求/refresh接口，该接口位于spring-boot-starter-actuator依赖，调用前需添加否则404。 -
publicclassAPIAccountController{ -
-
@ApiOperation(value ="用户登陆") -
@RequestMapping(value ="acc/login", method ={RequestMethod.POST }) -
publicRestAPIResult<String> login(@ApiParam(value ="手机号")@RequestParam(required =true)String phone, -
@ApiParam(value ="密码")@RequestParam(required =true)String password,HttpSession session){ -
RestAPIResult<String> restAPIResult =newRestAPIResult<>(); -
Account account = accountFeignClient.login(phone, password); -
}
使用swagger进行API管理的话，对代码有一定的侵入性，这个需要考虑在内。之前也提到过几种在线API的管理方式，点击链接《介绍几款常用的在线API管理工具》
使用SpringBoot技术，再以maven原始的方式引入swagger使用的话，远不如一个starter来的爽，这里介绍一个swagger-starter，可以更快捷的与spring boot集成使用。
swagger-spring-boot-starter应用
在pom.xml中引入依赖：【当前最新版本 1.7.0.RELEASE】
-
<dependency> -
<groupId>com.spring4all</groupId> -
<artifactId>swagger-spring-boot-starter</artifactId> -
<version>1.7.0.RELEASE</version> -
</dependency>
注意：从1.6.0开始，我们按Spring Boot官方建议修改了artifactId为swagger-spring-boot-starter，1.6.0之前的版本不做修改，依然为使用spring-boot-starter-swagger !
在应用主类中增加@EnableSwagger2Doc注解
-
@EnableSwagger2Doc -
@SpringBootApplication -
publicclassBootstrap{ -
-
publicstaticvoid main(String[] args){ -
SpringApplication.run(Bootstrap.class, args); -
} -
-
}
默认情况下就能产生所有当前Spring MVC加载的请求映射文档。
参数配置，配置示例
-
swagger.enabled=true -
-
swagger.title=spring-boot-starter-swagger -
swagger.description=Starterfor swagger 2.x -
swagger.version=1.4.0.RELEASE -
swagger.license=ApacheLicense,Version2.0 -
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html -
-
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger -
-
swagger.contact.name=didi -
swagger.contact.url=http://blog.didispace.com -
-
swagger.contact.email=dyc87112@qq.com -
swagger.base-package=com.didispace -
swagger.base-path=/** -
swagger.exclude-path=/error, /ops/** -
-
swagger.globalOperationParameters[0].name=name one -
swagger.globalOperationParameters[0].description=some description one -
swagger.globalOperationParameters[0].modelRef=string -
swagger.globalOperationParameters[0].parameterType=header -
swagger.globalOperationParameters[0].required=true -
swagger.globalOperationParameters[1].name=name two -
swagger.globalOperationParameters[1].description=some description two -
swagger.globalOperationParameters[1].modelRef=string -
swagger.globalOperationParameters[1].parameterType=body -
swagger.globalOperationParameters[1].required=false -
-
// 取消使用默认预定义的响应消息,并使用自定义响应消息 -
swagger.apply-default-response-messages=false -
swagger.global-response-message.get[0].code=401 -
swagger.global-response-message.get[0].message=401get -
swagger.global-response-message.get[1].code=500 -
swagger.global-response-message.get[1].message=500get -
swagger.global-response-message.get[1].modelRef=ERROR -
swagger.global-response-message.post[0].code=500 -
swagger.global-response-message.post[0].message=500post -
swagger.global-response-message.post[0].modelRef=ERROR
详细介绍可参考源码，地址：https://github.com/SpringForAll/spring-boot-starter-swagger。由于JDK代码编译版本的限制，JDK1.7是不支持的，可使用1.8
扩展阅读：