YApi使用swagger导入接口无headers参数

雨点打透心脏的1/2处 2022-04-04 03:14 778阅读 0赞

## 1、问题描述 ##

在API文档与接口自动化测试对接时，使用原有是swagger导入接口，导入后接口参数信息自动罗列，但是进行自动化测试每个接口都需要相应的header信息，如果需要手动添加则大量复制工作降低效率

## 2、解决方法 ##

### 1、在swagger配置文件中统一加上header参数，然后再导入 ###

#### （1）修改swagger配置如下： ####

@Configuration
    @EnableSwagger2
    public class SwaggerConfig { 
    
        @Value("${swagger.host:}")
        private String host;
    
        @Bean
        public Docket buildAppDocket() { 
            ParameterBuilder tokenPar = new ParameterBuilder();
            List<Parameter> pars = new ArrayList<>();
            tokenPar.name("Content-Type").description("").modelRef(new ModelRef("string")).defaultValue("application/json").parameterType("header").required(true).build();
            pars.add(tokenPar.build());
            tokenPar.name("accessToken").description("登录token").modelRef(new ModelRef("string")).parameterType("header").required(true).build();
            pars.add(tokenPar.build());
            tokenPar.name("clientId").description("客戶端id").parameterType("header").modelRef(new ModelRef("string")).required(true).build();
            pars.add(tokenPar.build());
            tokenPar.name("userId").description("用户id").modelRef(new ModelRef("string")).parameterType("header").required(true).build();
            pars.add(tokenPar.build());
            return new Docket(DocumentationType.SWAGGER_2)
                    .host(host)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.zrk.study"))
                    .build()
                    .globalOperationParameters(pars);//添加参数
        }
    
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("接口文档").build();
        }

可以定义ParameterBuilder 设置实际开发中所需要的请求头参数信息放入list中，然后在build()**后** 调用globalOperationParameters(pars)方法添加参数即可

#### （2）导入 ####

*  URL导入模式  
    ![操作截图][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIxMDY3MzA3_size_16_color_FFFFFF_t_70]  
    **服务器地址**\+/actuator/swagger-docs，即为swagger url，并需要选择自己想把接口导入哪个分类，如上图“公共分类”，  
    注：需要在服务器上部署并启动该微服务
 *  JSON文件导入模式  
    ![操作截图][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIxMDY3MzA3_size_16_color_FFFFFF_t_70 1]  
    如果微服务部署到服务器并启动微服务或者本地启动该微服务，可以使用postman访问**服务器地址**\+/actuator/swagger-docs接口接口，将返回json保存成json文件如swagger.json,直接拖入到上图下面红框内即可导入

### 2、熟悉swagger.json文件的话可以修改json文件（需要大量粘贴复制，但比较灵活） ###

{ 
        "swagger": "2.0",
        "info": { 
            "title": "接口文档"
        },
        "host": "127.0.0.1:30091",
        "basePath": "/",
        "tags": [
            { 
                "name": "study-center"
            }
        ],
        "paths": { 
            "/study-center/first/getClassInfo": { 
                "get": { 
                    "tags": [
                        "study-center"
                    ],
                    "summary": "获取班级信息",
                    "description": "",
                    "operationId": "getClassInfoUsingGET",
                    "produces": [
                        "*/*"
                    ],
                    "parameters": [
                        { 
                            "name": "Content-Type",
                            "in": "header",
                            "required": true,
                            "type": "string",
                            "default": "application/json"
                        },
                        { 
                            "name": "accessToken",
                            "in": "header",
                            "description": "登录token",
                            "required": true,
                            "type": "string"
                        },
                        { 
                            "name": "clientId",
                            "in": "header",
                            "description": "客戶端id",
                            "required": true,
                            "type": "string"
                        },
                        { 
                            "name": "userId",
                            "in": "header",
                            "description": "用户id",
                            "required": true,
                            "type": "string"
                        },
                        { 
                            "name": "classId",
                            "in": "query",
                            "description": "classId",
                            "required": true,
                            "type": "integer",
                            "format": "int32"
                        }
                    ],
                    "responses": { 
                        "200": { 
                            "description": "OK",
                            "schema": { 
                                "$ref": "#/definitions/ReturnStatus"
                            }
                        },
                        "401": { 
                            "description": "Unauthorized"
                        },
                        "403": { 
                            "description": "Forbidden"
                        },
                        "404": { 
                            "description": "Not Found"
                        }
                    },
                    "deprecated": false
                }
            },
            "/study-center/first/getTeacherInfo": { 
                "get": { 
                    "tags": [
                        "study-center"
                    ],
                    "summary": "获取老师信息",
                    "description": "",
                    "operationId": "getTeacherInfoUsingGET",
                    "produces": [
                        "*/*"
                    ],
                    "parameters": [
                        { 
                            "name": "Content-Type",
                            "in": "header",
                            "required": true,
                            "type": "string",
                            "default": "application/json"
                        },
                        { 
                            "name": "accessToken",
                            "in": "header",
                            "description": "登录token",
                            "required": true,
                            "type": "string"
                        },
                        { 
                            "name": "clientId",
                            "in": "header",
                            "description": "客戶端id",
                            "required": true,
                            "type": "string"
                        },
                        { 
                            "name": "userId",
                            "in": "header",
                            "description": "用户id",
                            "required": true,
                            "type": "string"
                        },
                        { 
                            "name": "teacherId",
                            "in": "query",
                            "description": "teacherId",
                            "required": true,
                            "type": "integer",
                            "format": "int32"
                        }
                    ],
                    "responses": { 
                        "200": { 
                            "description": "OK",
                            "schema": { 
                                "$ref": "#/definitions/ReturnStatus"
                            }
                        },
                        "401": { 
                            "description": "Unauthorized"
                        },
                        "403": { 
                            "description": "Forbidden"
                        },
                        "404": { 
                            "description": "Not Found"
                        }
                    },
                    "deprecated": false
                }
            }
        },
        "definitions": { 
            "ReturnStatus": { 
                "type": "object",
                "properties": { 
                    "data": { 
                        "type": "array",
                        "items": { 
                            "type": "object"
                        }
                    },
                    "page": { 
                        "$ref": "#/definitions/PageInfo"
                    },
                    "property": { 
                        "type": "object"
                    },
                    "status": { 
                        "$ref": "#/definitions/Status"
                    }
                },
                "title": "OperStatus"
            },
            "PageInfo": { 
                "type": "object",
                "properties": { 
                    "nextPage": { 
                        "type": "integer",
                        "format": "int32"
                    },
                    "pageSize": { 
                        "type": "integer",
                        "format": "int32"
                    },
                    "totalCou": { 
                        "type": "integer",
                        "format": "int32"
                    },
                    "totalPage": { 
                        "type": "integer",
                        "format": "int32"
                    }
                },
                "title": "PageInfo"
            },
            "Status": { 
                "type": "object",
                "properties": { 
                    "code": { 
                        "type": "integer",
                        "format": "int32"
                    },
                    "desc": { 
                        "type": "string"
                    }
                },
                "title": "Status"
            }
        }
    }

其中headers参数可以加在对应接口的parameters中，“in”取值为“header”  
注：上面json文件是在导出的正式环境的swagger.json文件基础上进行的删减跟修改，仅供参考

## 3、结果 ##

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIxMDY3MzA3_size_16_color_FFFFFF_t_70 2]  
***重新导入后，在Yapi操作页面找到对应接口可以看到已经有对应的headers参数信息，不需要每个接口一个一个字段复制***

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIxMDY3MzA3_size_16_color_FFFFFF_t_70]: /images/20220404/963a3d48407d418eb2c1f6cebec665cf.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIxMDY3MzA3_size_16_color_FFFFFF_t_70 1]: /images/20220404/6c56db67ffb44a5082ddf7bc2b6a4cac.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIxMDY3MzA3_size_16_color_FFFFFF_t_70 2]: /images/20220404/000fd412499e4882a9404e567fd10e70.png