使用swagger-codegen

·  阅读 359

这是我参与11月更文挑战的第6天,活动详情查看:2021最后一次更文挑战


由于需要接口文档与前端进行联调并且可以进行接口调试,选择了swagger、Stoplight作为解决方案。

一、使用swagger-codegen-cli

相关技术:

  • Swagger用于生成描述、调用和可视化RESTful风格的Web服务,支持通过OpenAPI文档自动生成接口文件。
  • Stoplight是设计API的图形界面工具,可以生成openAPI文档;支持GITHUB。
  • Swagger提供了swagger-codegen-cli包用于根据OpenAPI文档自动生成代码。

API的全称是应用编程接口(Application Programming Interface),这并不是一个新概念,在计算机操作系统出现的早期就已经存在了。在互联网时代,把网站的服务封装成一系列计算机易识别的数据接口开放出去,供第三方开发者使用,这种行为就叫做开放网站的API,与之对应的,所开放的API就被称作openAPI。

相关命令

swagger-codegen-cli 的相关命令:

$ java -jar swagger-codegen-cli.jar -help
usage: swagger-codegen [-h] Command ...

named arguments:
  -h, --help             show this help message and exit

commands:
  Command                additional help
    generate             generate 
    config-help          config-help 
    meta                 meta 
    langs                langs
    version              version
复制代码

例如,通过OpenAPI文档生成代码可以使用以下的命令

java -jar swagger-codegen-cli.jar \
generate -i cos.yaml \
--api-package com.test.pj.controller.api \
--model-package com.test.pj.controller.model \
--invoker-package com.test.pj.invoker \
--group-id com.test \
--artifact-id pj \
--artifact-version 0.0.1-SNAPSHOT \
-l spring \
--library spring-mvc \
-o cos628
复制代码

generate 是主命令,表示进行代码生成;其余命令的含义如下:

  • -i 定义读取的OpenAPI文档
  • --api-package 定义控制器的包名
  • --model-package 定义实体(entity)的包名
  • --invoker-package 定义反射类存放的包名
  • --group-id 定义项目pom文件的group-id
  • --artifact-id 定义项目pom文件的group-id
  • --artifact-version 定义项目pom文件的artifact-version
  • -l 置生成的语言
  • --library 置使用的库
  • -o 设置输出目录

生成默认项目

swagger-codegen-cli.jar所在目录执行以下命令,可以生成cosim-swagger-meta文件夹。

java -jar swagger-codegen-cli.jar meta -o cosim-swagger-meta
复制代码

项目的默认结构如下:

.
|- README.md    // this file
|- pom.xml      // build script
|-- src
|--- main
|---- java
|----- io.swagger.codegen.DefaultGenerator.java // generator file
|---- resources
|----- default // template files
|----- META-INF
|------ services
|------- io.swagger.codegen.CodegenConfig
复制代码

一般是通过修改DefaultGenerator.java类自定义生产代码的配置,而自定义生成模板还需要修改api.mustache定义接口以及添加文件apiController.mustache生产实现类,这两个资源文件的格式是mustache

二、什么是mustache

mustache 是一种特殊的模板引擎语言,适用于Ruby、Python、Java等,详情可以见首页。Mustache 可用于 HTML、配置文件、源代码以及其他格式的数据。它的工作原理是使用散列或对象中提供的值扩展模板中的标签

mustache 是无逻辑的,没有if-elsewhile等逻辑语句,只有一个个标签。通过解析标签、填充数据,最终生成指定格式的代码。

标签(tag)

  • 标签 通过两个大括号表示,即{{}}

  • 最基本的标签类型是变量{{name}}。会在模板文件中查询名为name的键;如果没有name键,将递归检查父上下文。如果到达顶部上下文name但仍未找到键,则不会呈现任何内容

  • 默认情况下,所有变量都是 HTML 转义的;如果要返回未转义的 HTML,请使用三重大括号:{{{name}}}

  • mustache还支持通过&取消转义变量:{{& name}}

  • 默认情况下,变量“miss”返回一个空字符串,但是这个默认值也是可以配置的。

部分(Sections)

Sections会根据当前上下文中键的值呈现文本块一次或多次,它是以#字符开始,又以/结束。

  • 如果键存在且值为 false 或空列表,则不会显示Sections包装的数据
  • 如果键存在并且具有非假值,则示Sections包装将被呈现并显示一次或多次
  • 支持函数或 lambda
  • 当该值为非假但不是列表时,它将用作块的单个渲染的上下文。

例如:

Template:

Shown.
{{#person}}
  Never shown!
{{/person}}
复制代码

Hash:

{
  "person": false
}
复制代码

Output:

Shown.
复制代码

倒置部分(Inverted Sections)

Inverted Sections以【`】符号开始,以\结束;它可以基于键的反向值渲染一次文本

Template:

{{#repo}}
  <b>{{name}}</b>
{{/repo}}
{{^repo}}
  No repos :(
{{/repo}}
复制代码

Hash:

{
  "repo": []
}
复制代码

Output:

No repos :(
复制代码

注释

注释通过{{!}}包装,在生成时回被忽略,例如:

<h1>Today{{! ignore me }}.</h1>
复制代码

局部(Partial )

局部以大于号开头,例如{{> box}},与包含、导入、模板扩展、嵌套模板或子模板类似,这个是一个扩展的功能,可以将上下文的数据引入到子文件中。例如:

base.mustache:
<h2>Names</h2>
{{#names}}
  {{> user}}
{{/names}}

user.mustache:
<strong>{{name}}</strong>
复制代码

等价于:

<h2>Names</h2>
{{#names}}
  <strong>{{name}}</strong>
{{/names}}
复制代码

三、参考资料

swagger-codegen mustache

分类:
后端
标签:
分类:
后端
标签:
收藏成功!
已添加到「」, 点击更改