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

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

一、使用`swagger-codegen-cli`

相关命令

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-else或while等逻辑语句，只有一个个标签。通过解析标签、填充数据，最终生成指定格式的代码。

标签（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

使用swagger-codegen

一、使用swagger-codegen-cli