# SpringCloud 两种方法整合 Swagger、常用 Swagger注解

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();}@Beanpublic 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();}@Beanpublic 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;@AutowiredRouteLocator routeLocator;@Beanpublic 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();}@Overridepublic 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(){
    }