基于Springcloud的微服务生成标准化接口文档（Swagger)

最新推荐文章于 2024-04-18 16:12:57 发布

张大仙000

最新推荐文章于 2024-04-18 16:12:57 发布

阅读量1.3k

点赞数

分类专栏：微服务源码 spring boot 文章标签： java spring

本文链接：https://blog.csdn.net/zhang_ming_xuan/article/details/106786588

版权

源码同时被 3 个专栏收录

4 篇文章 0 订阅

订阅专栏

微服务

1 篇文章 0 订阅

订阅专栏

spring boot

1 篇文章 0 订阅

订阅专栏

摘要：

公司基于springcloud架构搭建了一整套的后端服务，按业务模块进行服务的拆分和数据库的隔离，使用了eureka,zuul这些中间件来实现服务的访问的依赖，接口文档之前一直都是使用文档的方式进行维护，无法及时的更新。

使用文档维护接口的方式会带来已下弊端：

修改字段往往不能及时更新文档，前后端开发人员口头沟通，后期查看困难
文档层次不清晰，想找一个接口很困难。
接口请求数据校验麻烦，非空字段都需要挨个判断并手动返回描述信息

为了解决上面的问题，考虑引入第三方插件的方式来实现标准的api文档

主要的集成方式参考：https://juejin.im/post/5dcc00c2e51d45105d56306e

这里主要介绍针对zuul网关来支持多个服务的api

网关配置：

首先在公共module引入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>
<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
</dependency>

2. 把zuul的route服务都加入到resoures

@Profile({"dev","test"})表示只有在开发和测试环境能够查看文档，网关服务也会有接口，所有需要把zuulapi加入

要访问swagger的ui页面需要放行几个url:

业务服务配置

@Configuration
@EnableSwagger2
@Profile({"dev","test"})
public class SwaggerConfig {
//    @Bean
//    public Docket createRestApi() {
//        ParameterBuilder tokenPar = new ParameterBuilder();
//        List<Parameter> pars = new ArrayList<Parameter>();
//        tokenPar.name("Authorization").description("token令牌")
//                .modelRef(new ModelRef("string"))
//                .parameterType("header")
//                .required(true).build();
//        pars.add(tokenPar.build());
//        Docket docket=new Docket(DocumentationType.SWAGGER_2)
//                .globalOperationParameters(pars)
//                .securitySchemes(securitySchemes())
//                .securityContexts(securityContexts())
//                .apiInfo(apiInfo())
//                .select()
//                //为当前包路径
//                .apis(RequestHandlerSelectors.basePackage("com.wlines.simpleaccess.controller"))
//                .paths(PathSelectors.any())
//                .build();
//
//        return docket;
        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
//    }

    @Bean
    public Docket defaultApi() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否启用
                .enable(true);
        ApiSelectorBuilder builder = docket.select();
        //api过滤
//        builder = builder.apis(Predicates.or(apisFilter()));
        //接口路径过滤

		//全局header参数
		ParameterBuilder tokenPar = new ParameterBuilder();
		List<Parameter> pars = new ArrayList<Parameter>();
		tokenPar.name("Authorization").description("token令牌")
				.modelRef(new ModelRef("string"))
				.parameterType("header")
				.required(true).build();
		pars.add(tokenPar.build());
		docket.globalOperationParameters(pars);

        //使用认证上下文
        docket.securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
        return builder.build();
    }

    private List<ApiKey> securitySchemes() {
        return Lists.newArrayList(
                new ApiKey("Authorization", "Authorization", "header"));
    }


    private List<SecurityContext> securityContexts() {
        return Lists.newArrayList(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        //正则式过滤,此处是所有非login开头的接口都需要认证
                        .forPaths(PathSelectors.regex("^(?!login).*$"))
                        .build()
        );
    }
    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "认证权限");
        return Lists.newArrayList(
                new SecurityReference("Authorization", new AuthorizationScope[]{authorizationScope}));
    }


    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("服务 API")
                //创建人
                .contact(new Contact("wlines", "https://www.wlines.cn", ""))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}

项目采用oauth2授权，所以需要配置授权，在文档页面需要填入token

接口输入参数注解说明

需要注意两点

接口不能使用requestmapping接收参数，这样在文档中会生成多个接口
@RequestBody接参数不要使用JSONObject接参，直接使用实体

对于分页定义一个统一的接收实体：

/**
 * 分页请求参数基类
 */
@Getter
@Setter
@ToString
@ApiModel
public class PageBaseParam {
    @ApiModelProperty(value = "页数,从0开始")
    @NotBlank(message="不能为空")
    private int page;

    @ApiModelProperty(value = "每页条数")
    @NotBlank(message="不能为空")
    private int limit;

    @ApiModelProperty(value = "模糊查找条件")
    private String label;

    @ApiModelProperty(value = "项目id")
    private int projectId;

    @JsonFormat(timezone = "GMT+8", pattern = "yyyy-MM-dd HH:mm:ss")
    @ApiModelProperty(value = "开始时间")
    private LocalDateTime startTime;

    @JsonFormat(timezone = "GMT+8", pattern = "yyyy-MM-dd HH:mm:ss")
    @ApiModelProperty(value = "结束时间")
    private LocalDateTime endTime;
    @ApiModelProperty(value = "开始日期")
    private LocalDate startDate;
    @ApiModelProperty(value = "结束日期")
    private LocalDate endDate;
}

定义统一的返回实体：

@ApiModel(value = "统一返回")
public class ApiResult4Swagger<T> {
    @ApiModelProperty(value = "返回消息")
    private String msg;
    @ApiModelProperty(value = "返回码")
    private String code;
    @ApiModelProperty(value = "数据")
    private T data;
    private PageModel page;

    public static ApiResult4Swagger isSuccess(){
        ApiResult4Swagger msg=new ApiResult4Swagger();
        msg.setCode(SUCCESS);
        msg.setMsg("操作成功");
        return msg;
    }

    public static ApiResult4Swagger isSuccess(String msg){
        ApiResult4Swagger result=new ApiResult4Swagger();
        result.setCode(SUCCESS);
        result.setMsg(msg);
        return result;
    }

    public static ApiResult4Swagger isParamError(){
        ApiResult4Swagger msg=new ApiResult4Swagger();
        msg.setCode(CODE.PARAM_ERROR);
        return msg;
    }
    public static ApiResult4Swagger isParamError(String m){
        ApiResult4Swagger msg=new ApiResult4Swagger();
        msg.setCode(CODE.PARAM_ERROR);
        msg.setMsg(m);
        return msg;
    }

    public static ApiResult4Swagger isResultError(String m){
        ApiResult4Swagger msg=new ApiResult4Swagger();
        msg.setCode(CODE.RESULT_ERROR);
        msg.setMsg(m);
        return msg;
    }

    public static ApiResult4Swagger isException(String err){
        ApiResult4Swagger msg=new ApiResult4Swagger();
        msg.setCode(CODE.EXCEPTION);
        msg.setMsg(err);
        msg.setData(err);
        return msg;
    }

    public static ApiResult4Swagger isSuccess(Object data){
        ApiResult4Swagger msg=new ApiResult4Swagger();
        msg.setMsg("操作成功");
        msg.setCode(SUCCESS);
        msg.setData(data);
        return msg;
    }

    public static ApiResult4Swagger isSuccess(List data){
        ApiResult4Swagger msg=new ApiResult4Swagger();
        msg.setMsg("操作成功");
        msg.setCode(SUCCESS);
        msg.setData(data);
        return msg;
    }

    public static ApiResult4Swagger isSuccess(long total, List list){
        ApiResult4Swagger msg=new ApiResult4Swagger();
        msg.setMsg("操作成功");
        msg.setCode(SUCCESS);
        msg.setData(list);
        msg.setPage(new PageModel(total));
        return msg;
    }

    public boolean isOk(){
        if(StringUtils.equals(SUCCESS,code)){
            return true;
        }
        return false;
    }

    public PageModel getPage() {
        return page;
    }

    public void setPage(PageModel page) {
        this.page = page;
    }

    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }

    public String getCode() {
        return code;
    }

    public void setCode(String code) {
        this.code = code;
    }

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }


    public static class CODE{
        public static final String SUCCESS="200";
        public static final String AUTH_ERROR="401";//权限错误
        public static final String TOKEN_ERROR="402";//token错误
        public static final String PARAM_ERROR="403";//参数错误
        public static final String OPE_ERROR="405";//错误操作
        public static final String EXCEPTION="500";//发生异常
        public static final String RESULT_ERROR="500";//发生异常
    }
}

张大仙000

关注

0
点赞
踩
2

收藏

觉得还不错? 一键收藏
0
评论
基于Springcloud的微服务生成标准化接口文档（Swagger)

摘要：公司基于springcloud架构搭建了一整套的后端服务，按业务模块进行服务的拆分和数据库的隔离，使用了eureka,zuul这些中间件来实现服务的访问的依赖，接口文档之前一直都是使用文档的方式进行维护，无法及时的更新。使用文档维护接口的方式会带来已下弊端：修改字段往往不能及时更新文档，前后端开发人员口头沟通，后期查看困难文档层次不清晰，想找一个接口很困难。接口请求数据校验麻烦，非空字段都需要挨个判断并手动返回描述信息为了解决上面的问题，考虑引入第三方插件的方式来实现标准的api
复制链接

扫一扫