Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。
通过在controller中添加注解，即可轻易实现代码文档化。
Swagger提供ui界面，方便查看接口说明和测试接口功能。
本文主要讲解如何创建一个swagger 的springboot starter项目，只要在其他服务中引入该starter.并添加相关注解，即可完成接口文档化。
并讲解了如何在spring cloud zuul网关中引入swagger，为前端提供统一的访问入口。
本文的完整代码:GitHub:swagger-starter。
创建sawgger-springboot-starter项目
ＰＯＭ配置
pom引入swagger依赖
<!-- swagger 依赖 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
pom引入springboot starter相关依赖
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-configuration-processor</artifactId> <optional>true</optional> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency>
swagger配置
相关的配置属性，将会在yml文件中进行配置
package com.swagger.config; import lombok.Data; import org.springframework.boot.context.properties.ConfigurationProperties; @Data @ConfigurationProperties(prefix = "swagger") public class SwaggerProperties { //需要扫描的包路径 private String basePackage = "com"; //显示的标题 private String title = "swagger"; //联系人 private String contactName; //联系地址 private String contactUrl; //联系邮件地址 private String contactEmail; //文档版本号 private String version; //描述 private String description; // private String termsOfServiceUrl; private String license; private String licenseUrl; }
配置类
package com.swagger.config; import lombok.extern.slf4j.Slf4j; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.context.properties.EnableConfigurationProperties; 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.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger.web.UiConfiguration; /** *功能描述 * @author lgj * @Description swagger 配置类 * @date 6/5/19 */ @Slf4j @Configuration @EnableConfigurationProperties(SwaggerProperties.class) public class SwaggerConfig { @Autowired private SwaggerProperties swaggerProperties; @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() //为当前包路径 .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage())) .paths(PathSelectors.any()) .build(); } //构建 api文档的详细信息函数,注意这里的注解引用的是哪个 private ApiInfo apiInfo() { log.info("swaggerProperties = " + swaggerProperties); return new ApiInfoBuilder() //页面标题 .title(swaggerProperties.getTitle()) //创建人 .contact(new Contact(swaggerProperties.getContactName(), swaggerProperties.getContactUrl(), swaggerProperties.getContactEmail())) //版本号 .version(swaggerProperties.getVersion()) //描述 .description(swaggerProperties.getDescription()) .license(swaggerProperties.getLicense()) .licenseUrl(swaggerProperties.getLicenseUrl()) .termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl()) .build() ; } @Bean UiConfiguration uiConfig() { return new UiConfiguration(null, "list", "alpha", "schema", UiConfiguration.Constants.DEFAULT_SUBMIT_METHODS, false, true, 60000L); } }
既然作为starter，还需要指定项目启动时的配置类，因为其他项目引用时没有指定扫描该类，那么就不会创建相关的bean。
因此需要在starter中指定。
在resource中创建文件 META-INF/spring.factories
spring.factories文件内容，通过EnableAutoConfiguration指定。
org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.swagger.config.SwaggerConfig
swagger-springboot-starter创建完成。
创建一个WEB应用进行测试
引入上面starter的依赖
<dependency> <groupId>com.swagger</groupId> <artifactId>swagger-springboot-starter</artifactId> <version>1.0.0</version> </dependency>
yml中进行相关的配置
server:
port: 8900
swagger:
basePackage: com
title: "demo ui doc"
contactName: "libai"
contactUrl: contactUrl-demo
contactEmail: contactEmail-demo
version: v1.0.0
description: description-demo
termsOfServiceUrl: termsOfServiceUrl-demo
license: license-demo
licenseUrl: licenseUrl-demo
创建一个controller
package com.demo.demo; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import java.util.Date; @Api(value = "/demo",description = "demo controller") @RestController @RequestMapping("/demo") public class WebController { @ApiOperation(value = "/demo/1",notes="这是demo1",tags="{tag1,tag2}",response=String.class,httpMethod= "GET") @ApiParam(name = "name",value = "libai") @GetMapping("/1") public String demo1(String name){ return name + ":" + new Date().toString(); } @ApiOperation(value = "/demo/2",notes="这是demo2",tags="{tag3,tag4}",response=String.class,httpMethod= "POST") @PostMapping("/2") public String demo2(String name){ return name + ":" + new Date().toString(); } }
注意这里使用@Api和@ApiOperation,@ApiParam等实现接口说明。
主要说明相关的类和方法。以便swagger-ui查看到。
更多使用方法参考本博文
在启动类上添加注解@EnableSwagger2
@EnableSwagger2 @SpringBootApplication public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }
测试
启动DemoApplication应用，访问swagger-ui界面，地址http://localhost:8900/swagger-ui.html
可以看到之前代码中的相关配置。
同时，它还可以实现对接口的测试
SpringCloud Zuul中引入
在使用spring cloud进行开发时，如果每个微服务都引入sawgger，每个微服务都是单独的访问地址，如果有几百个微服务，对swagger进行管理访问将会比较麻烦。因此需要在zuul网关提供统一的访问入口。
pom中引入zuul和swagger依赖
<!-- swagger 依赖 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/org.springframework.cloud/spring-cloud-starter-netflix-zuul --> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-netflix-zuul</artifactId> <version>2.1.0.RELEASE</version> </dependency>
yml中配置
server:
port: 8902
zuul:
routes:
#demo系统
demo:
path: /demo/**
url: http://localhost:8900
yml中配置的是demo应用的路由配置，当访问 http://localhost:8902/demo/**/** 时，将会转发到http://localhost:8900.也就是demo应用。
swagger 资源配置
package com.zuul.demo.swagger; import org.springframework.context.annotation.Primary; import org.springframework.stereotype.Component; import springfox.documentation.swagger.web.SwaggerResource; import springfox.documentation.swagger.web.SwaggerResourcesProvider; import springfox.documentation.swagger2.annotations.EnableSwagger2; import java.util.ArrayList; import java.util.List; /** *功能描述 * @author lgj * @Description * @date 6/5/19 */ @EnableSwagger2 @Component @Primary public class SwaggerResources implements SwaggerResourcesProvider { @Override public List<SwaggerResource> get() { List resources = new ArrayList<>(); resources.add(swaggerResource("demo模块", "/demo/v2/api-docs", "2.0")); return resources; } private SwaggerResource swaggerResource(String name, String location, String version) { SwaggerResource swaggerResource = new SwaggerResource(); swaggerResource.setName(name); swaggerResource.setLocation(location); swaggerResource.setSwaggerVersion(version); return swaggerResource; } }
swaggerResource("demo模块", "/demo/v2/api-docs", "2.0")
注意这里的location值，对应的是yml中的配置/demo + /v2/api-docs,可修改的是参数name。
demo:
path: /demo/**
url: http://localhost:8900
如果有新模块需要添加
user-app: path: /user/** url: http://localhost:8903
只需要在这里添加如下代码即可。
resources.add(swaggerResource("user模块", "/user/v2/api-docs", "2.0"));
启动类
package com.zuul.demo; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.cloud.netflix.zuul.EnableZuulProxy; @EnableZuulProxy @SpringBootApplication public class ZuulApplication { public static void main(String[] args) { SpringApplication.run(ZuulApplication.class, args); } }
测试
启动zuul应用，访问地址:http://localhost:8902/swagger-ui.html
在右上角的"Select a spec"可以选择查看对应模块的API文档。
如果出现以下错误，则说明没有添加注解@EnableSwagger2
完成!!!!!!!!!!!!!!