swagger-codegen 生成代码原理

刺骨的言语ヽ痛彻心扉 2024-04-19 12:59 2阅读 0赞

### 文章目录 ###

*   *   *  概述：
         *  一.命令行入口
         *  二.web调用
         *  三.总指挥官
         *   *  1.生成models
             *  2.生成apis
             *  3.生成支持文件

### 概述： ###

swagger-codegen可以通过命令行生成代码（*v2.1.5 /Swagger格式*），也可以通过web服务生成代码（*v3.0.11/OpenAPI格式*）。两者只是入口不一样，但实际都是调用的**DefaultGenerator.generate**（）来生成代码。

在整个生成代码的过程中，主要是 **OpenAPI/Swagger**，不同语言的**CodegenConfig**实现类（可以继承这个来实现自定义的处理方式），**DefaultGenerator**三者发挥着重要作用。

1.  OpenAPI/Swagger用于装载代码信息（包括项目版本信息，server，标签，路径，返回参数类等）；
2.  CodegenConfig是一个接口，不同语言会有对应的实现类，用于处理数据或者承载代码所共有的信息（比如文件路径，自定义标签信息等）；
3.  DefaultGenerator就是生成代码的总指挥官，它会有所有的信息，包括了OpenAPI/Swagger，CodegenConfig所拥有的信息。

v2.1.5源码：https://github.com/swagger-api/swagger-codegen  
v3.0.11源码：https://github.com/swagger-api/swagger-codegen/tree/v3.0.11

### 一.命令行入口 ###

SwaggerCodegen.main：

public class SwaggerCodegen {
        public static void main(String[] args) {
            String version = Version.readVersionFromResources();
            @SuppressWarnings("unchecked")
            Cli.CliBuilder<Runnable> builder =
                    Cli.<Runnable>builder("swagger-codegen-cli")
                            .withDescription(
                                    String.format(
                                            "Swagger code generator CLI (version %s). More info on swagger.io",
                                            version))
                            .withDefaultCommand(Langs.class)
                //这里有Generate.class，其内部有run方法
                            .withCommands(Generate.class, Meta.class, Langs.class, Help.class,
                                    ConfigHelp.class, Validate.class, Version.class);
    		//调用上述Generate的run()
            builder.build().parse(args).run();
        }
    }

Generate.run:

public void run() {
    	......
    
        //设置代码数据
        if (isNotEmpty(spec)) {
            configurator.setInputSpec(spec);
        }
    	//设置语言种类
        if (isNotEmpty(lang)) {
            configurator.setLang(lang);
        }
        //设置各种参数值
        ......
        applySystemPropertiesKvpList(systemProperties, configurator);
        applyInstantiationTypesKvpList(instantiationTypes, configurator);
        applyImportMappingsKvpList(importMappings, configurator);
        applyTypeMappingsKvpList(typeMappings, configurator);
        applyAdditionalPropertiesKvpList(additionalProperties, configurator);
        applyLanguageSpecificPrimitivesCsvList(languageSpecificPrimitives, configurator);
        applyReservedWordsMappingsKvpList(reservedWordsMappings, configurator);
        //转换成ClientOptInput
        final ClientOptInput clientOptInput = configurator.toClientOptInput();
    
        new DefaultGenerator().opts(clientOptInput).generate();
    }

CodegenConfigurator.toClientOptInput:

public ClientOptInput toClientOptInput() {
    
        Validate.notEmpty(lang, "language must be specified");
        Validate.notEmpty(inputSpec, "input spec must be specified");
    
        setVerboseFlags();
        setSystemProperties();
    
        CodegenConfig config = CodegenConfigLoader.forName(lang);
    
        //设置各种属性
    	......
    
        //处理动态属性至additionalProperties（如：XXXCodegen）
        handleDynamicProperties(config);
    
        if (isNotEmpty(library)) {
            config.setLibrary(library);
        }
    
        config.additionalProperties().putAll(additionalProperties);
    
        //设置对应语言的CodegenConfig
        ClientOptInput input = new ClientOptInput()
                .config(config);
    
        final List<AuthorizationValue> authorizationValues = AuthParser.parse(auth);
    
        //读取输入的数据
        Swagger swagger = new SwaggerParser().read(inputSpec, authorizationValues, true);
    
        input.opts(new ClientOpts())
                .swagger(swagger);
    
        return input;
    }

### 二.web调用 ###

GeneratorController

package io.swagger.v3.generator.online;
    
        public ResponseContext generate(RequestContext context, GenerationRequest generationRequest) {
            //预处理一些信息（比如：处理生成代码的路径）
            ......
            //调用生成代码的接口
            ResponseContext responseContext = generate(generationRequest, outputRootFolder, outputContentFolder, outputFile);
            LOGGER.debug("generate end - " + requestLog);
            return responseContext;
    
        }
    
        private ResponseContext generate(GenerationRequest generationRequest, File outputRootFolder, File outputContentFolder, File outputFile) {
            //生成器服务，用于配置CodegenConfig等
            GeneratorService generatorService = new GeneratorService();
            try {
                generatorService.generationRequest(generationRequest);
            } catch (Exception e) {
                String msg = "Error processing generation request: " + e.getMessage();
                LOGGER.error(msg, e);
                return new ResponseContext()
                        .status(400)
                        .contentType(MediaType.TEXT_PLAIN)
                        .entity(msg);
            }
    
            final List<File> files;
            try {
                //1.生成代码！
                files = generatorService.generate();
            } catch (Exception e) {
                String msg = String.format("Error generating `%s` code : %s", generationRequest.getLang(), e.getMessage());
                LOGGER.error(msg, e);
                return new ResponseContext()
                        .status(500)
                        .contentType(MediaType.TEXT_PLAIN)
                        .entity(msg);
            }
           ......
        }

1.生成代码 GeneratorService.generate：也是调用的DefaultGenerator.opts(XXX)和DefaultGenerator.generate（）

opts方法主要是配置相关的信息，生成代码还是靠generate方法

public List<File> generate() {
        //v3对应着3.0.11 OpenAPI的代码数据
        if (optsV3 != null) {
            return new DefaultGenerator().opts(optsV3).generate();
        } else if (optsV2 != null) {
             //v2对应着swagger的代码数据
            return new io.swagger.codegen.DefaultGenerator().opts(optsV2).generate();
        }
        throw new RuntimeException("missing opts input");
    }

### 三.总指挥官 ###

*这里分析的是3.0.11的DefaultGenerator*

DefaultGenerator.generate:

生成各种文件的流程是：处理数据，找到模板，生成文件

public List<File> generate() {
    
        if (swagger == null || config == null) {
            throw new RuntimeException("missing swagger input or config!");
        }
        //添加一些生成器属性（名字，版本，生成时间等）和测试数据
        configureGeneratorProperties();
        //添加appname，license等信息
        configureSwaggerInfo();
    
        //处理model里面内联（包括array）
        InlineModelResolver inlineModelResolver = new InlineModelResolver();
        inlineModelResolver.flatten(swagger);
    
        List<File> files = new ArrayList<File>();
        // 1.生成models
        List<Object> allModels = new ArrayList<Object>();
        generateModels(files, allModels);
        // 2.生成apis
        List<Object> allOperations = new ArrayList<Object>();
        generateApis(files, allOperations, allModels);
    
        // 3.生成支持文件的数据
        Map<String, Object> bundle = buildSupportFileBundle(allOperations, allModels);
        // 生成支持文件，就是除去api和model所需要的文件
        generateSupportingFiles(files, bundle);
        config.processSwagger(swagger);
        //返回生成的所有文件
        return files;
    }

#### 1.生成models ####

private void generateModels(List<File> files, List<Object> allModels) {
    
        if (!generateModels) {
            return;
        }
    
        //获取所有的model数据
        final Map<String, Schema> schemas = this.openAPI.getComponents().getSchemas();
        if (schemas == null) {
            return;
        }
    ......
    
        for (String name : modelKeys) {
            try {
                //不需要生成可以导入的类
                if(config.importMapping().containsKey(name)) {
                    LOGGER.info("Model " + name + " not imported due to import mapping");
                    continue;
                }
                Schema schema = schemas.get(name);
                Map<String, Schema> schemaMap = new HashMap<>();
                schemaMap.put(name, schema);
                //处理model数据（包括了包路径，属性信息）
                Map<String, Object> models = processModels(config, schemaMap, schemas);
                //存放类名
                //toModelName多处使用，为了统一名字格式（非字母下划线数字字符会被去掉）
                models.put("classname", config.toModelName(name));
                models.putAll(config.additionalProperties());
                allProcessedModels.put(name, models);
    
                final List<Object> modelList  = (List<Object>) models.get("models");
    
                if (modelList == null || modelList.isEmpty()) {
                    continue;
                }
    
                //处理内部类？
                for (Object object : modelList) {
                    Map<String, Object> modelMap = (Map<String, Object>) object;
                    CodegenModel codegenModel = null;
                    if (modelMap.containsKey("oneOf-model")) {
                        codegenModel = (CodegenModel) modelMap.get("oneOf-model");
                    }
                    if (modelMap.containsKey("anyOf-model")) {
                        codegenModel = (CodegenModel) modelMap.get("anyOf-model");
                    }
                    if (codegenModel != null) {
                        models = processModel(codegenModel, config, schemas);
                        models.put("classname", config.toModelName(codegenModel.name));
                        models.putAll(config.additionalProperties());
                        allProcessedModels.put(codegenModel.name, models);
                        break;
                    }
                }
            } catch (Exception e) {
                throw new RuntimeException("Could not process model '" + name + "'" + ".Please make sure that your schema is correct!", e);
            }
        }
    
        // 预处理model
        allProcessedModels = config.postProcessAllModels(allProcessedModels);
    
        for (String modelName: allProcessedModels.keySet()) {
            //获取model信息
            Map<String, Object> models = (Map<String, Object>)allProcessedModels.get(modelName);
            try {
                //不需要生成importMapping中有的类
                if(config.importMapping().containsKey(modelName)) {
                    continue;
                }
                //获取模板
                Map<String, Object> modelTemplate = (Map<String, Object>) ((List<Object>) models.get("models")).get(0);
                if (isJavaCodegen(config.getName())) {
                    // 特殊处理java别名
                    if (modelTemplate != null && modelTemplate.containsKey("model")) {
                        CodegenModel codegenModel = (CodegenModel) modelTemplate.get("model");
                        Map<String, Object> vendorExtensions = codegenModel.getVendorExtensions();
                        boolean isAlias = false;
                        if (vendorExtensions.get(CodegenConstants.IS_ALIAS_EXT_NAME) != null) {
                            isAlias = Boolean.parseBoolean(vendorExtensions.get(CodegenConstants.IS_ALIAS_EXT_NAME).toString());
                        }
                        if (isAlias) {
                            continue;  
                        }
                    }
                }
                allModels.add(modelTemplate);
                for (String templateName : config.modelTemplateFiles().keySet()) {
                    String suffix = config.modelTemplateFiles().get(templateName);
                    String filename = config.modelFileFolder() + File.separator + config.toModelFilename(modelName) + suffix;
                    if (!config.shouldOverwrite(filename)) {
                        LOGGER.info("Skipped overwriting " + filename);
                        continue;
                    }
                    //根据模板生成代码
                    File written = processTemplateToFile(models, templateName, filename);
                    if(written != null) {
                        files.add(written);
                    }
                }
                if(generateModelTests) {
                    //生成测试代码
                    generateModelTests(files, models, modelName);
                }
                if(generateModelDocumentation) {
                    // 生成doc
                    generateModelDocumentation(files, models, modelName);
                }
            } catch (Exception e) {
                throw new RuntimeException("Could not generate model '" + modelName + "'", e);
            }
        }
       ......
    }

#### 2.生成apis ####

private void generateApis(List<File> files, List<Object> allOperations, List<Object> allModels) {
        if (!generateApis) {
            return;
        }
        boolean hasModel = true;
        if (allModels == null || allModels.isEmpty()) {
            hasModel = false;
        }
    
        //获取所有整理过的路径信息
        Map<String, List<CodegenOperation>> paths = processPaths(this.openAPI.getPaths());
        Set<String> apisToGenerate = null;
        String apiNames = System.getProperty("apis");
        if(apiNames != null && !apiNames.isEmpty()) {
            apisToGenerate = new HashSet<String>(Arrays.asList(apiNames.split(",")));
        }
        if(apisToGenerate != null && !apisToGenerate.isEmpty()) {
            Map<String, List<CodegenOperation>> updatedPaths = new TreeMap<>();
            for(String m : paths.keySet()) {
                if(apisToGenerate.contains(m)) {
                    updatedPaths.put(m, paths.get(m));
                }
            }
            paths = updatedPaths;
        }
        //生成每个api类
        for (String tag : paths.keySet()) {
            try {
                List<CodegenOperation> ops = paths.get(tag);
                Collections.sort(ops, new Comparator<CodegenOperation>() {
                    @Override
                    public int compare(CodegenOperation one, CodegenOperation another) {
                        return ObjectUtils.compare(one.operationId, another.operationId);
                    }
                });
                //获取api代码所需要的所有信息
                Map<String, Object> operation = processOperations(config, tag, ops, allModels);
    
                //路径对应OpenAPI的server的url
                operation.put("basePath", basePath);
                //没有host的路径
                operation.put("basePathWithoutHost", basePathWithoutHost);
                operation.put("contextPath", contextPath);
                //标签名字，用于关联path（operation）
                operation.put("baseName", tag);
                //model包路径
                operation.put("modelPackage", config.modelPackage());
                operation.putAll(config.additionalProperties());
                //类名 toApiName会生成驼峰格式的类名
                operation.put("classname", config.toApiName(tag));
                operation.put("classVarName", config.toApiVarName(tag));
                operation.put("importPath", config.toApiImport(tag));
                //类的文件名
                operation.put("classFilename", config.toApiFilename(tag));
    
                //额外的信息（可以包含自定义信息）
                if(!config.vendorExtensions().isEmpty()) {
                    operation.put("vendorExtensions", config.vendorExtensions());
                }
    
                // Pass sortParamsByRequiredFlag through to the Mustache template...
                boolean sortParamsByRequiredFlag = true;
                if (this.config.additionalProperties().containsKey(CodegenConstants.SORT_PARAMS_BY_REQUIRED_FLAG)) {
                    sortParamsByRequiredFlag = Boolean.valueOf(this.config.additionalProperties().get(CodegenConstants.SORT_PARAMS_BY_REQUIRED_FLAG).toString());
                }
                operation.put("sortParamsByRequiredFlag", sortParamsByRequiredFlag);
    
                operation.put("hasModel", hasModel);
    
    
                allOperations.add(new HashMap<>(operation));
                for (int i = 0; i < allOperations.size(); i++) {
                    Map<String, Object> oo = (Map<String, Object>) allOperations.get(i);
                    if (i < (allOperations.size() - 1)) {
                        oo.put("hasMore", "true");
                    }
                }
    
                for (String templateName : config.apiTemplateFiles().keySet()) {
                    String filename = config.apiFilename(templateName, tag);
                    if (!config.shouldOverwrite(filename) && new File(filename).exists()) {
                        LOGGER.info("Skipped overwriting " + filename);
                        continue;
                    }
    
                    //根据模板生成代码
                    File written = processTemplateToFile(operation, templateName, filename);
                    if(written != null) {
                        files.add(written);
                    }
                }
    
                if(generateApiTests) {
                    // 生成api测试文件
                    for (String templateName : config.apiTestTemplateFiles().keySet()) {
                        String filename = config.apiTestFilename(templateName, tag);
                        // do not overwrite test file that already exists
                        if (new File(filename).exists()) {
                            LOGGER.info("File exists. Skipped overwriting " + filename);
                            continue;
                        }
    
                        File written = processTemplateToFile(operation, templateName, filename);
                        if (written != null) {
                            files.add(written);
                        }
                    }
                }
    
    
                if(generateApiDocumentation) {
                    // 生成api doc
                    for (String templateName : config.apiDocTemplateFiles().keySet()) {
                        String filename = config.apiDocFilename(templateName, tag);
                        if (!config.shouldOverwrite(filename) && new File(filename).exists()) {
                            LOGGER.info("Skipped overwriting " + filename);
                            continue;
                        }
    
                        File written = processTemplateToFile(operation, templateName, filename);
                        if (written != null) {
                            files.add(written);
                        }
                    }
                }
    
            } catch (Exception e) {
                throw new RuntimeException("Could not generate api file for '" + tag + "'", e);
            }
        }
     ......
    }

#### 3.生成支持文件 ####

private void generateSupportingFiles(List<File> files, Map<String, Object> bundle) {
        if (!generateSupportingFiles) {
            return;
        }
        Set<String> supportingFilesToGenerate = null;
        String supportingFiles = System.getProperty(CodegenConstants.SUPPORTING_FILES);
        boolean generateAll = false;
        if (supportingFiles != null && supportingFiles.equalsIgnoreCase("true")) {
            generateAll = true;
        } else if (supportingFiles != null && !supportingFiles.isEmpty()) {
            supportingFilesToGenerate = new HashSet<>(Arrays.asList(supportingFiles.split(",")));
        }
    
        for (SupportingFile support : config.supportingFiles()) {
            try {
                //生成文件和模板名字
                ......
                //根据模板生成支持文件
                if(ignoreProcessor.allowsFile(new File(outputFilename))) {
                    if (templateFile.endsWith("mustache")) {
                        String rendered = templateEngine.getRendered(templateFile, bundle);
                        writeToFile(outputFilename, rendered);
                        files.add(new File(outputFilename));
                    } else {
                        InputStream in = null;
    
                        try {
                            in = new FileInputStream(templateFile);
                        } catch (Exception e) {
                            // continue
                        }
                        if (in == null) {
                            in = this.getClass().getClassLoader().getResourceAsStream(getCPResourcePath(templateFile));
                        }
                        File outputFile = new File(outputFilename);
                        OutputStream out = new FileOutputStream(outputFile, false);
                        if (in != null) {
                            LOGGER.info("writing file " + outputFile);
                            IOUtils.copy(in, out);
                            out.close();
                        } else {
                            LOGGER.warn("can't open " + templateFile + " for input");
                        }
                        files.add(outputFile);
                    }
                } else {
                    LOGGER.info("Skipped generation of " + outputFilename + " due to rule in .swagger-codegen-ignore");
                }
            } catch (Exception e) {
                throw new RuntimeException("Could not generate supporting file '" + support + "'", e);
            }
        }
    
        //需要则生成 .swagger-codegen-ignore 
        final String swaggerCodegenIgnore = ".swagger-codegen-ignore";
        String ignoreFileNameTarget = config.outputFolder() + File.separator + swaggerCodegenIgnore;
        File ignoreFile = new File(ignoreFileNameTarget);
        if (generateSwaggerMetadata && !ignoreFile.exists()) {
            String ignoreFileNameSource = File.separator + config.getCommonTemplateDir() + File.separator + swaggerCodegenIgnore;
            String ignoreFileContents = readResourceContents(ignoreFileNameSource);
            try {
                writeToFile(ignoreFileNameTarget, ignoreFileContents);
            } catch (IOException e) {
                throw new RuntimeException("Could not generate supporting file '" + swaggerCodegenIgnore + "'", e);
            }
            files.add(ignoreFile);
        }
    
        if(generateSwaggerMetadata) {
            //生成swagger元数据
            final String swaggerVersionMetadata = config.outputFolder() + File.separator + ".swagger-codegen" + File.separator + "VERSION";
            File swaggerVersionMetadataFile = new File(swaggerVersionMetadata);
            try {
                writeToFile(swaggerVersionMetadata, ImplementationVersion.read());
                files.add(swaggerVersionMetadataFile);
            } catch (IOException e) {
                throw new RuntimeException("Could not generate supporting file '" + swaggerVersionMetadata + "'", e);
            }
        }
    
    }