配置swagger2 ,单controller层和多controller层配置 ,整合swagger-bootstrap-ui ,微服务集群搭建swagger

男娘i 2022-03-01 11:06 1100阅读 0赞

# 单SpringBoot项目配置swaggerAPI文档 #

1.添加maven依赖

<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>

2.添加swagger配置类

@Configuration
 @EnableSwagger2
 public class Swagger2 {
 /**
 * 创建API应用
 * apiInfo() 增加API相关信息
 * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
 * 本例采用指定扫描的包路径来定义指定要建立API的目录。
 */
 @Bean
 public Docket createRestApi(){
 com.google.common.base.Predicate<RequestHandler> selector1 = RequestHandlerSelectors.basePackage("com.cnczsq.mall.elephant.v1.controller");
 com.google.common.base.Predicate<RequestHandler> selector2 = RequestHandlerSelectors.basePackage("com.cnczsq.mall.elephant.v2.controller");
 return new Docket(DocumentationType.SWAGGER_2)
 .apiInfo(apiInfo())
 .select()
 //为当前包下controller生成API文档 //单个配置controller
 //.apis(RequestHandlerSelectors.basePackage("com.cnczsq.mall.elephant.v1.controller")) 
 //controller批量配 方式一
 .apis(Predicates.or(selector1,selector2))
 // controller批量配方式二 指定所有controller的都实现的一个接口，比如@RestController
 //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
 // controller批量配方式三 指定所有controller路径的父级
 //.apis(RequestHandlerSelectors.basePackage("com.cnczsq.mall.elephant"))
 // controller批量配方式四 指定所有ApiOperation注解方法
 //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
 .paths(PathSelectors.any())
 .build();
 //添加登录认证
 .securitySchemes(securitySchemes()) //下面这两个不是必须
 .securityContexts(securityContexts());
 }
 
 /**
 * 创建该API的基本信息（这些基本信息会展现在文档页面中）
 * 访问地址：http://项目实际地址/swagger-ui.html
 * @return
 */
 private ApiInfo apiInfo() {
 return new ApiInfoBuilder()
 .title("Spring Boot中使用Swagger2")
 .description("更多请关注http://www.hao123.com")
 .termsOfServiceUrl("http://www.baidu.com")
 .contact("zsq")
 .version("1.0")
 .build();
 }
 
 //end 简单配置到这里基本就够了
 
 private List<ApiKey> securitySchemes() {
 //设置请求头信息
 List<ApiKey> result = new ArrayList<>();
 ApiKey apiKey = new ApiKey("Authorization", "Authorization", "header");
 result.add(apiKey);
 return result;
 }
 
 private List<SecurityContext> securityContexts() {
 //设置需要登录认证的路径
 List<SecurityContext> result = new ArrayList<>();
 result.add(getContextByPath("/brand/.*"));
 return result;
 }
 
 private SecurityContext getContextByPath(String pathRegex){
 return SecurityContext.builder()
 .securityReferences(defaultAuth())
 .forPaths(PathSelectors.regex(pathRegex))
 .build();
 }
 
 private List<SecurityReference> defaultAuth() {
 List<SecurityReference> result = new ArrayList<>();
 AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
 AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
 authorizationScopes[0] = authorizationScope;
 result.add(new SecurityReference("Authorization", authorizationScopes));
 return result;
 }
 }

3.编写测试controller

@Api(tags = "V1-AdminController" ,description = "牛的不行")
    @RestController
    @RequestMapping("/admin")
    public class AdminController {
    
        @ApiOperation(value = "测试",notes = "返回测试信息")
        @GetMapping("/select")
        @ApiImplicitParam(paramType = "query"  ,name = "name",value = "用户名")
        public Object select(String name){
            return name+"123";
        }
    
    }

4.访问swagger  [http://localhost:8090/swagger-ui.html\#/][http_localhost_8090_swagger-ui.html]    ip 端口号填自己的   ok

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nc2hlbmdxaWFuZzE2OA_size_16_color_FFFFFF_t_70][]

**Swagger使用的注解及其说明：**

[@Api][Api]：用在类上，说明该类的作用。

@ApiOperation：注解来给API增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

l   **code**：数字，例如400

l   **message**：信息，例如"请求参数没填好"

l   **response**：抛出异常的类

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

l   **@ApiModelProperty**：描述一个model的属性

注意：@ApiImplicitParam的参数说明：

<table> 
 <tbody> 
 <tr> 
 <td> paramType：指定参数放在哪个地方 </td> 
 <td> header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）--&gt;请求参数的获取：@PathVariable body：（不常用） form（不常用） </td> 
 </tr> 
 <tr> 
 <td> name：参数名 </td> 
 <td> &nbsp; </td> 
 </tr> 
 <tr> 
 <td> dataType：参数类型 </td> 
 <td> &nbsp; </td> 
 </tr> 
 <tr> 
 <td> required：参数是否必须传 </td> 
 <td> true | false </td> 
 </tr> 
 <tr> 
 <td> value：说明参数的意思 </td> 
 <td> &nbsp; </td> 
 </tr> 
 <tr> 
 <td> defaultValue：参数的默认值 </td> 
 </tr> 
 </tbody> 
</table>

# 整合swagger-bootstrap-ui #

### 在原基础上添加如下配置 ###

<dependency>
 <groupId>com.github.xiaoymin</groupId>
 <artifactId>swagger-bootstrap-ui</artifactId>
 <version>1.9.3</version>
 </dependency>

添加

@Configuration
    public class WebMvcConfig extends WebMvcConfigurationSupport {
        /**
         * 静态资源配置(默认)
         */
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");// 静态资源路径
            registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
            registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
            super.addResourceHandlers(registry);
        }
    }

[http://localhost:8888/doc.html][http_localhost_8888_doc.html]     [http://localhost:8888/swagger-ui.html\#/][http_localhost_8888_swagger-ui.html]   都能访问

# 微服务集群搭建swagger #

1.选择一个子服务member服务,添加pom.xml依赖

<dependency>
 <groupId>com.spring4all</groupId>
 <artifactId>swagger-spring-boot-starter</artifactId>
 <version>1.9.0.RELEASE</version>
 </dependency>
 
 <dependency>
 <groupId>com.github.xiaoymin</groupId>
 <artifactId>swagger-bootstrap-ui</artifactId>
 <version>1.9.3</version>
 </dependency>

2.application.properties配置文件 配置swagger的 controller扫包位置

swagger.base-package=zhang.controller

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nc2hlbmdxaWFuZzE2OA_size_16_color_FFFFFF_t_70 1][]

3.启动类开启swagger注解   @EnableSwagger2Doc ,到此一个子服务配置完成,按照此方法再配置一个order子服务

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nc2hlbmdxaWFuZzE2OA_size_16_color_FFFFFF_t_70 2][]

4.配置Zuul网关服务Swagger ,按照上述配置进行配置完毕,然后添加swagger来源配置类

//swagger2添加文档来源 配置
 @Component
 @Primary
 public class DocumentConfig implements SwaggerResourcesProvider {
 @Override
 public List<SwaggerResource> get() {
 List<SwaggerResource> resources=new ArrayList<>();
 resources.add(swaggerResource("member","/api-member/v2/api-docs","2.0"));
 resources.add(swaggerResource("order","/api-order/v2/api-docs","2.0"));
 return resources;
 }
 
 /**
 * @param name 一般起服务别名
 * @param localhost 地址 网关配置以/api-member/**路径访问member服务 故这里以 /api-member开头配置
 * 网关配置以/api-order/**路径访问order服务 故这里以 /api-order开头配置
 * @param version 版本
 */
 private SwaggerResource swaggerResource(String name,String localhost,String version) {
 SwaggerResource swaggerResource=new SwaggerResource();
 swaggerResource.setName(name);
 swaggerResource.setLocation(localhost);
 swaggerResource.setSwaggerVersion(version);
 return swaggerResource;
 }
 }

5.直接访问,Zuul网关端口为80 ,  [http://localhost:80/doc.html][http_localhost_8888_doc.html]     [http://localhost:80/swagger-ui.html\#/][http_localhost_8888_swagger-ui.html]   都能访问![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nc2hlbmdxaWFuZzE2OA_size_16_color_FFFFFF_t_70 3][]

[http_localhost_8090_swagger-ui.html]: http://localhost:8090/swagger-ui.html#/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nc2hlbmdxaWFuZzE2OA_size_16_color_FFFFFF_t_70]: /images/20220301/b0651f793449446684bcbc6489ce2007.png
[Api]: https://my.oschina.net/u/2396174
[http_localhost_8888_doc.html]: http://localhost:8888/doc.html
[http_localhost_8888_swagger-ui.html]: http://localhost:8888/swagger-ui.html#/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nc2hlbmdxaWFuZzE2OA_size_16_color_FFFFFF_t_70 1]: /images/20220301/976d64ad2bf64a52bff75083c13c09e0.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nc2hlbmdxaWFuZzE2OA_size_16_color_FFFFFF_t_70 2]: /images/20220301/cbfd1e0d4bbd47709cd9d6034e0604c9.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poYW5nc2hlbmdxaWFuZzE2OA_size_16_color_FFFFFF_t_70 3]: /images/20220301/e0e0733257fc46e688bedee27d2a0244.png