首页 > 其他分享 >codegen的使用方法及常见参数配置

codegen的使用方法及常见参数配置

时间:2024-04-15 17:48:37浏览次数:22  
标签:api 常见 生成 codegen -- API 参数 swagger

前言

在进行API开发时,我们通常需要定义API的接口规范和文档,以方便其他开发者调用和使用。Swagger是一款非常流行的API文档生成工具,它可以帮助我们快速生成API接口文档,并提供了许多便捷的功能。本文将介绍如何使用swagger-codegen来生成API接口文档。

简介

swagger-codegen是Swagger官方提供的一个代码生成工具,它可以根据Swagger规范文件生成各种语言的API客户端和服务端代码。swagger-codegen支持的语言包括Java、Python、Go、Ruby等多种语言,可以方便地生成符合规范的API代码。

安装

使用swagger-codegen需要先安装它,可以通过以下命令来安装:

npm install -g swagger-codegen

使用

安装完成后,我们可以通过以下命令来生成API客户端或服务端代码:

swagger-codegen generate -i <input-file> -l <language> -o <output-directory>

其中,为Swagger规范文件的路径,为要生成的代码的语言,为输出目录。例如,要生成Java客户端代码,可以使用以下命令:

swagger-codegen generate -i swagger.json -l java -o ./client

这条命令会根据swagger.json文件生成Java客户端代码,并将代码保存到./client目录下。

除了生成客户端代码外,swagger-codegen还支持生成服务端代码。要生成服务端代码,可以使用以下命令:

swagger-codegen generate -i swagger.json -l <language> -o ./server

其中,为要生成的服务端代码的语言,例如Java、Python等。

2. 常见参数配置

2.1 指定生成的API客户端库

使用-l参数可以指定生成的API客户端库的语言。例如,要生成Java客户端库,可以使用以下命令:

java -jar swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l java -o /path/to/output/directory
2.2 指定生成的服务器端代码

使用-l参数可以指定生成的服务器端代码的语言。例如,要生成Node.js服务器端代码,可以使用以下命令:

java -jar swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l nodejs-server -o /path/to/output/directory
2.3 指定生成的API文档格式

使用-l参数可以指定生成的API文档的格式。例如,要生成HTML格式的API文档,可以使用以下命令:

java -jar swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l html -o /path/to/output/directory
2.4 指定生成的API代码包名/命名空间

使用--api-package参数可以指定生成的API代码的包名或命名空间。例如,要将生成的Java API代码放在com.example.api包下,可以使用以下命令:

java -jar swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l java --api-package com.example.api -o /path/to/output/directory
2.5 指定生成的模型代码包名/命名空间

使用--model-package参数可以指定生成的模型代码的包名或命名空间。例如,要将生成的Java模型代码放在com.example.model包下,可以使用以下命令:

java -jar swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l java --model-package com.example.model -o /path/to/output/directory
2.6 指定生成的API接口前缀

使用--api-package参数可以指定生成的API接口的前缀。例如,要将生成的Node.js API接口前缀设置为/api/v1,可以使用以下命令:

java -jar swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l nodejs-server --api-package /api/v1 -o /path/to/output/directory
类名

我们可以通过配置参数来指定生成的类的名称。默认情况下,类名是根据API的路径和操作名称生成的。例如,对于路径为/pet,操作名称为POST的API,生成的类名为PetApi。如果我们想要指定自己的类名,可以使用--api-package参数。例如,我们可以使用以下命令来生成一个名为MyPetApi的类:

swagger-codegen generate -i petstore.yaml -l java -o /path/to/output --api-package com.example.api --model-package com.example.model --api-name MyPetApi
描述

我们可以通过配置参数来指定生成的类的描述。默认情况下,类的描述是从API的description字段中获取的。如果我们想要指定自己的描述,可以使用--api-description参数。例如,我们可以使用以下命令来生成一个类,并指定其描述为This is my API

swagger-codegen generate -i petstore.yaml -l java -o /path/to/output --api-package com.example.api --model-package com.example.model --api-description "This is my API"
方法名

我们可以通过配置参数来指定生成的方法的名称。默认情况下,方法名是根据操作名称生成的。例如,对于操作名称为createPet的API,生成的方法名为createPet。如果我们想要指定自己的方法名,可以使用--api-name参数。例如,我们可以使用以下命令来生成一个方法,并指定其名称为addPet

swagger-codegen generate -i petstore.yaml -l java -o /path/to/output --api-package com.example.api --model-package com.example.model --api-name MyPetApi --api-operation-name addPet

配置文件的方式

swagger-codegen 的配置文件是一个 JSON 格式的文件,可以通过 -c 参数指定。下面是一个简单的配置文件示例:

{
  "packageName": "com.example",
  "description": "This is a sample API",
  "apiPackage": "com.example.api",
  "modelPackage": "com.example.model",
  "modelFiles": {
    "User": {
      "description": "A user object",
      "className": "User",
      "template": "User.mustache",
      "importMapping": {
        "DateTime": "org.joda.time.DateTime"
      }
    }
  }
}

配置文件参数说明

  • packageName: 生成代码的包名。

  • description: API 的描述信息。

  • apiPackage: 生成 API 类的包名。

  • modelPackage: 生成模型类的包名。

  • modelFiles: 模型类的配置信息,其中每个键值对表示一个模型类。

  • description: 模型类的描述信息。

  • className: 模型类的类名。

  • template: 模型类的模板文件名。

  • importMapping: 模型类中需要导入的类的映射关系。

配置文件的使用

在生成代码时,我们可以通过 -c 参数指定配置文件的路径。例如:

swagger-codegen generate -i swagger.json -l java -c config.json -o output/

这样,swagger-codegen 就会根据配置文件中的参数生成代码。

其他参数

除了上述常见的配置参数外,还有许多其他的参数可以用来控制生成的代码的细节。例如,我们可以使用--model-name-prefix参数来指定生成的模型类的名称前缀,使用--model-name-suffix参数来指定生成的模型类的名称后缀,使用--date-library参数来指定日期类型的库等等。具体的参数可以参考swagger-codegen的官方文档https://swagger.io/tools/swagger-codegen/ https://github.com/swagger-api/swagger-codegen/issues/7795 https://github.com/swagger-api/swagger-codegen#generating-a-client-library。

总结

swagger-codegen是一个非常方便的API代码生成工具,可以帮助我们快速生成符合规范的API客户端和服务端代码。使用swagger-codegen可以大大提高API开发的效率,减少开发者的工作量。希望本文对大家有所帮助。

标签:api,常见,生成,codegen,--,API,参数,swagger
From: https://www.cnblogs.com/bigleft/p/18136578

相关文章

  • 【知识点】常见的SQL优化手段
    问:有哪些常见的SQL优化手段?这也是个高频面试题,并且并非面试造火箭的那种问题,实际项目中也会有非常多的地方需要进行SQL优化避免使用Select*select*中,无用字段会增加网络带宽消耗,特别是varchar、blob、text等大字段select*无法使用Mysql优化器覆盖索引的优化。覆盖索......
  • codegen的模板文件mustache中配置在swagger规范文档中自定义属性
    在使用swagger-codegen生成代码时,我们经常需要使用自定义属性来生成我们需要的代码。swagger-codegen使用了mustache模板引擎来生成代码,而在mustache模板文件中,我们可以通过配置swagger规范文档中的自定义属性来生成我们需要的代码。本篇文章将从第三级标题开始,详细介绍如何在swag......
  • codegen的模板文件mustache中,classname,description,notes如何赋值
    Swagger-codegen的模板文件mustacheSwagger-codegen是一个开源的代码生成工具,它可以根据Swagger规范自动生成客户端和服务器端代码。在使用Swagger-codegen时,我们可以通过mustache模板文件来自定义生成的代码。在这篇文章中,我们将介绍如何在mustache模板文件中给classname、descr......
  • layUI Table自定义工具栏和搜索参数
    layUITable自定义工具栏和搜索参数视频讲解地址https://www.bilibili.com/video/BV1P94y197nNHTML代码<divclass="container-fluid"><tableclass="layui-hide"id="test"lay-filter="test"></table></div><s......
  • centos7 安装supervisor教程以及常见问题
    目录简介Supervisor是一个进程控制系统。它是一个C/S系统(注意:其提供WEB接口给用户查询和控制)。它允许用户去监控和控制在类UNIX系统的进程。它的目标与launchd、daemontools和runit有些相似。但是与它们不一样的是、它不是作为init(进程号pid是1)运行。它是......
  • 函数的参数传递是值传递
    1.基本值,会直接将值传递给函数的参数2.引用值传递,是将引用值地址值传递给函数参数外界定义的a并没有被修改引用地址,说明参数传递进来的是地址值,如果参数是引用传递,那么外界的a应该被修改为a=此时值被改变,是直接操作了引用对象地址指向的内存空间,函数参数传递进......
  • LlamaIndex 常见问题解答(FAQ)
     提示:如果您尚未完成,请安装LlamaIndex并完成起步教程。遇到不熟悉的术语时,请参考高层次概念部分。在这个章节中,我们将从您为起步示例编写的代码开始,展示您可能希望针对不同应用场景对其进行的常见定制方法:python fromllama_index.coreimportVectorStoreIndex,Simp......
  • 参数,名称空间,作用域
    1函数的调用方式【1】直接调用函数名()-->调用函数defstudent(name,age):print(f"mynameis{name},myageis{age}")#函数名()-->调用函数student(name="silence",age=16)#mynameissilence,myageis16【2】用表达式调用函数用一个新变量存储函数的内......
  • 13-axios 传递参数的方式(data 与 params 的区别)
    Axios官方网址:起步|Axios中文文档|Axios中文网(axios-http.cn)参考文章:axios传递参数的方式(data与params的区别)-知乎(zhihu.com) Axiosa大家都非常的清楚,一个既可以用于客户端或者 服务端发送http请求的库。但是在前后端联调的时候有的时候会很难受,所以这里我......
  • 实现自定义注解校验方法参数(AOP+自定义注解+自定义异常+全局异常捕获)
    一、实现目的在编写接口的时候,通常会先对参数进行一次校验,这样业务逻辑代码就略显冗杂,如果可以把校验参数的代码进行统一管理,在方法或者属性上直接添加注解就可以实现参数的校验,就可以提升代码编写的效率。二、实现原理通过自定义注解,注解在入参VO的属性上,设定需要满足的条件,然......