创建swagger的springboot-stater,并在spring cloud zuul网关中引入

Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。

通过在controller中添加注解，即可轻易实现代码文档化。

Swagger提供ui界面，方便查看接口说明和测试接口功能。

swagger-github 

 

本文主要讲解如何创建一个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

 

完成!!!!!!!!!!!!!!