SpringCloud 两种方法整合 Swagger、常用 Swagger注解
Swagger优点
- 统一的
API
文档管理,可以方便接口开发和使用。 - 提供测试功能,方便在线测试
- 说明接口
方法一:每个模块引用Swagger的配置
pom.xml
<!-- swagger2.0集成 -->
<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>
Swagger
配置类
@EnableSwagger2
@Configuration
public class SwaggerConfig {
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("springcloud最佳实践")
.description("SpringCloud集成Swagger") .termsOfServiceUrl("https://blog.csdn.net/qq_37248504/")
.contact("MarlonBrando")
.license("MarlonBrando")
.licenseUrl("#").version("1.0").build();
}
@Bean
public Docket newsApi() {
Docket docket = new Docket(DocumentationType.SWAGGER_2);
docket.enable(true);
docket.apiInfo(apiInfo())
.select()
//借口扫描的路径
.apis(RequestHandlerSelectors.basePackage("com.li"))
.paths(PathSelectors.any()).build();
return docket;
}
}
Spring Cloud
中单独的模块启动类:项目中启动这模块,会配置swagger
,需要的模块引入swaager
就可以
@SpringBootApplication
public class OsCoreServerApplication {
public static void main(String[] args) {
SpringApplication.run(OsCoreServerApplication.class, args);
}
}
- 模块的启动类中引入
Swagger
的配置类
@SpringBootApplication
@Import({com.li.os_core.config.SwaggerConfig.class})
public class MenuApplication {
public static void main(String[] args) {
SpringApplication.run(MenuApplication.class, args);
}
}
方法一在访问
Swagger
的接口文档时候,因为每个模块都引入了Swagger
的配置,在访问的时候只
能用localhost:模块端口号/ swagger-ui.html
进行访问。这种方式比较繁琐,每个模块的Swagger
接口得要去不同的端口访问。
方法二:统一网关(这个配置贼难受、模块的结构必须保持一致贼坑)
- 我的项目模块如下:
Eureka
为注册中心、ConfigServer
为本地文件系统、Menu
、Order
、Core
为服务模块,必须是SpringCloud
模块
Menu
和Order
模块为相同的服务模块他们的pom.xml
如下,先单独给每个模块配置swagger
,用各自的端口访问成功后,进行下面的集成。Order
和Menu
的pom.xml
<!-- 父模块-->
<parent>
<artifactId>OnlineShop</artifactId>
<groupId>com.li</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>order</artifactId>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
<version>2.0.2.RELEASE</version>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-config</artifactId>
<version>2.0.2.RELEASE</version>
</dependency>
<!--swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.0</version>
</dependency>
</dependencies>
- 这两个模块下的
Swagger
配置类
@EnableSwagger2
@Configuration
public class SwaggerConfig {
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("springcloud最佳实践").description("SpringCloud集成Swagger")
.termsOfServiceUrl("https://blog.csdn.net/qq_37248504/article/details/106750307").contact("MarlonBrando")
.license("MarlonBrando ").licenseUrl("#").version("1.0").build();
}
@Bean
public Docket newsApi() {
Docket docket = new Docket(DocumentationType.SWAGGER_2);
docket.enable(true);
docket.apiInfo(apiInfo())
.select()
//借口扫描的路径
.apis(RequestHandlerSelectors.basePackage("com.li"))
.paths(PathSelectors.any()).build();
return docket;
}
}
这两个模块和方法一完全一致,必须能够通过自己的Ip端口访问swagger的地址。
Zuul模块集成Swagger
core
模块pom.xml
,其他依赖和上面的一样,因为都是子模块,添加zuul
的依赖
<!-- zuul 依赖 -->
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-netflix-zuul</artifactId>
</dependency>
- 编写
Swagger
的配置类
@EnableSwagger2
@Configuration
@Primary
public class SwaggerConfig implements SwaggerResourcesProvider {
//是否开启swagger,正式环境一般是需要关闭的,可根据springboot的多环境配置进行设置
@Value(value = "${swagger.enabled}")
Boolean swaggerEnabled;
@Autowired
RouteLocator routeLocator;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
// 是否开启
.enable(swaggerEnabled).select()
// 扫描的路径包
.apis(RequestHandlerSelectors.basePackage("com.li"))
// 指定路径处理PathSelectors.any()代表所有的路径
.paths(PathSelectors.any()).build().pathMapping("/");
}
//设置api信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("路由网关(Zuul):利用swagger2聚合API文档")
.description("测试接口文档")
// 作者信息
.contact(new Contact("MarlonBrando", "https://blog.csdn.net/qq_37248504/article/details/106750307", "1924086063@qq.com"))
.version("1.0.0")
.termsOfServiceUrl("https://blog.csdn.net/qq_37248504/")
.build();
}
@Override
public List<SwaggerResource> get() {
//利用routeLocator动态引入微服务
List<SwaggerResource> resources = new ArrayList<>();
resources.add(swaggerResource("zuul-gateway","/v2/api-docs","1.0"));
//循环 使用Lambda表达式简化代码
routeLocator.getRoutes().forEach(route ->{
//动态获取
resources.add(swaggerResource(route.getId(),route.getFullPath().replace("**", "v2/api-docs"), "1.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;
}
}
- 注意在每个模块的配置文件中加上
swagger:
enabled: true
core
模块启动类
@SpringBootApplication
@EnableZuulProxy
public class CoreApplication {
public static void main(String[] args) {
SpringApplication.run(CoreApplication.class, args);
}
}
- 项目启动可以各自访问
swagger
页面,也可以访问core
模块的,访问如下,可以切换路由进行访问。
Swagger 常用注解
@ApiOperation
描述接口的详细内容
@GetMapping("/findAll/{index}/{limit}")
@ApiOperation("菜单分页查询接口")
public List<Menu> findall(@PathVariable("index") int index,@PathVariable("limit") int limit){
return menuRepository.findAll(index,limit);
}
@ApiModel
描述实体类的相关信息
@ApiModel("这是Menu菜单,它的属性有")
public class Menu {
private int id;
private String name;
private Double price;
private String flavor;
private int type_id;
}
@Api
用在Controller
上面说明Controller
的信息
@Api("这是菜单的Controller")
@RestController
@RequestMapping("/menu")
public class MenuController {}
@ApiModelProperty
用在参数上说明参数的详细信息
@ApiModel("这是Menu菜单,它的属性有")
public class Menu {
@ApiModelProperty("菜单id")
private int id;
@ApiModelProperty("菜单名")
private String name;
@ApiModelProperty("价格")
private Double price;
@ApiModelProperty("口味")
private String flavor;
}
@ApiImplicitParams
方法参数的详细说明
@GetMapping("/findAll/{index}/{limit}")
@ApiOperation("菜单分页查询接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "index",value = "第几页"),
@ApiImplicitParam(name = "limit",value = "每页的大小")
})
public List<Menu> findall(@PathVariable("index") int index,@PathVariable("limit") int limit){
return menuRepository.findAll(index,limit);
}
@ApiResponses
@PostMapping("/test1")
@ApiResponses({
@ApiResponse(code=400,message = "参数不正确"),
@ApiResponse(code=500,message = "服务器错误")
})
public void test1(){}