java微服务子模块依赖于公共模块的 pom

转载

卫斯理 2024-09-13 00:24:33

文章标签 swagger List html spring 文章分类 Java 后端开发

单SpringBoot项目配置swaggerAPI文档

1.添加maven依赖

<!--Swagger-UI API文档生产工具-->
        <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#/ ip 端口号填自己的 ok

java微服务子模块依赖于公共模块的 pom_spring

Swagger使用的注解及其说明：

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

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

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

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

@ApiResponses：用于表示一组响应

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

l code：数字，例如400

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

l response：抛出异常的类

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

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

注意：@ApiImplicitParam的参数说明：

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

整合swagger-bootstrap-ui

在原基础上添加如下配置

<!--美化swagger-->
<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/swagger-ui.html#/ 都能访问

微服务集群搭建swagger

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

<!--springboot 整合swagger-->
        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.9.0.RELEASE</version>
        </dependency>
        <!--美化swagger-->
        <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

java微服务子模块依赖于公共模块的 pom_List_02

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

java微服务子模块依赖于公共模块的 pom_spring_03

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:80/swagger-ui.html#/ 都能访问

java微服务子模块依赖于公共模块的 pom_swagger_04