歪脖贰点零关注程序员个人成长
源码地址: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 -->
- <artifactId>springfox-swagger-ui</artifactId>
第二步编写配置管理类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页面
- public class Swagger2Config {
- @Bean
- public Docket createRestApi() {
- return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
- .apis(RequestHandlerSelectors.basePackage("com.simplemall.micro.serv.page.api"))
- .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
- .paths(PathSelectors.any())
- .build();
- }
- private ApiInfo apiInfo() {
- return new ApiInfoBuilder().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。
- public class APIAccountController {
- @ApiOperation(value = "用户登陆")
- @RequestMapping(value = "acc/login", method = { RequestMethod.POST })
- public RestAPIResult<String> login(@ApiParam(value = "手机号") @RequestParam(required = true) String phone,
- @ApiParam(value = "密码") @RequestParam(required = true) String password, HttpSession session) {
- RestAPIResult<String> restAPIResult = new RestAPIResult<>();
- 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】
- <groupId>com.spring4all</groupId>
- <artifactId>swagger-spring-boot-starter</artifactId>
- <version>1.7.0.RELEASE</version>
注意:从1.6.0开始,我们按Spring Boot官方建议修改了artifactId为swagger-spring-boot-starter,1.6.0之前的版本不做修改,依然为使用spring-boot-starter-swagger !
在应用主类中增加@EnableSwagger2Doc注解
- @EnableSwagger2Doc
- @SpringBootApplication
- public class Bootstrap {
- public static void main(String[] args) {
- SpringApplication.run(Bootstrap.class, args);
默认情况下就能产生所有当前Spring MVC加载的请求映射文档。
参数配置,配置示例
- swagger.enabled=true
- swagger.title=spring-boot-starter-swagger
- swagger.description=Starter for swagger 2.x
- swagger.version=1.4.0.RELEASE
- swagger.license=Apache License, Version 2.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
- [email protected]
- 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