Merge pull request #63 from baboy/master

feat: add @extension tag to support OpenApi extension
smart-doc-group · Mar 4, 2024 · efdb4d3 · efdb4d3
2 parents 8510886 + 696364c
commit efdb4d3
Show file tree

Hide file tree

Showing 3 changed files with 180 additions and 13 deletions.
diff --git a/docs/start/guide.md b/docs/start/guide.md
@@ -129,6 +129,7 @@ public String resp(@RequestBody String name){
 | [`@page`](#_4-page) | `@page` `tag` is used to annotate the method of `Controller` to indicate that the method is used to render and return a static page. If initiated when generating the `debug` page Test, the test page will automatically open a new tab in the browser to display the page. | `2.0.2` |
 | [`@ignoreParams`](#_5-ignoreparams) | `@ignoreParams` `tag` is used to mark the parameters that are ignored in the `Controller` method and do not want to be displayed in the document, for example: `@ignoreParams id name`, more Parameter names separated by spaces | `2.1.0` |
 | [`@response`(not recommended)](#_6-response is not recommended) | `@response` `tag` marked on the `Controller` method allows you to define the returned `json example` yourself. It is recommended to only use it when returning basic types, such as: `Result<String>` type. This generic type is a response to a simple native type. | `2.2.0` |
+| [`@extension`](#_7-extension) | `@extension` `tag` marked on the `Controller` method allows you to add a @extension tag to support openapi extension.  | `3.0.3` |
 
 > We are a tool that respects coding standards very much. We will not add anything randomly to mislead people. We will not provide things that are not provided by the current mainstream frameworks. We will only use tags more cautiously in the future.
 
@@ -325,6 +326,61 @@ public CommonResult<String> create() {
 }
 ```
 
+### 7. `@extension`
+@extension is marked on the controller method. it's used to support the extension feature of OpenApi. it will add a "x-*" attribution for openapi.json
+```java
+/**
+ * json file config test
+ * @tag dev
+ * @author cqmike 2021-07-16 14:09
+ **/
+@RestController
+public class ConfigRequestParamController {
+
+    /**
+     * get request test query param
+     * @extension group ecs
+     * @extension key1 ["v1","v2"]
+     * @extension key2 {"x":"v1", "y":"v2"}
+     * @tag test
+     * @author cqmike
+     * @return
+     */
+    @GetMapping("configQueryParamGet")
+    public void configQueryParamGet(String configQueryParam) {
+
+    }
+}
+```
+it will output extension tags in openapi.json:
+```
+{
+  "paths":{
+    "/xxx/xxx": {
+      "post": {
+        "summary": "xxx",
+        "tags": [
+          ...
+        ],
+        "requestBody": {
+          ...
+        },
+        "responses": {
+        ...
+        },
+        "operationId": "xxx-POST",
+        "x-group": "ecs",
+        "x-key1": ["v1","v2"],
+        "x-key2": {"x":"v1", "y":"v2"},
+        "parameters": [
+             ...
+        ]
+      }
+    }
+  }
+}
+```
+
 ## jsr
 
 | Function | Annotation |

diff --git a/docs/start/javadoc.md b/docs/start/javadoc.md
@@ -72,6 +72,7 @@ There are relatively few native Javadoc tags in Java, which cannot meet some usa
 | @ignoreParams             | @since smart-doc 2.1.0, ignoreParams tag is used to mark the parameters that do not want to be displayed in the document on the controller method, for example: @ignoreParams id name, multiple parameter names are separated by spaces                                                                                                                                                                                                                                                                                                                                                            |
 | @response                 | @since smart-doc 2.2.0, the response tag is marked on the controller method to allow you to define the returned json example by yourself. It is recommended to use it only when returning basic types, such as: Result<String> This generic type is a response of a simple primitive type.                                                                                                                                                                                                                                                                                                         |
 | @tag                      | @since 2.2.5, @tag is used to classify controller methods. You can assign methods under different controllers to multiple categories, and you can also directly assign controllers to one category or multiple categories.                                                                                                                                                                                                                                                                                                                                                                         |
+| @extension                | @since 3.0.3, @extension is marked on the controller method. it's used to support the extension feature of OpenApi. it will add a "x-*" attribution for openapi.json                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
 ## 2.1 @ignore use(deprecated using on field since 2.6.9)
 The @ignore annotation can only be applied to methods or classes, not on fields.
@@ -360,6 +361,61 @@ public class ConfigRequestParamController {
 ```
 @tag is used to classify controller methods. You can assign methods under different controllers to multiple categories, and you can also directly assign controllers to one category or multiple categories.
 
+## 2.8 @extension use
+@extension is marked on the controller method. it's used to support the extension feature of OpenApi. it will add a "x-*" attribution for openapi.json
+```java
+/**
+ * json file config test
+ * @tag dev
+ * @author cqmike 2021-07-16 14:09
+ **/
+@RestController
+public class ConfigRequestParamController {
+
+    /**
+     * get request test query param
+     * @extension group ecs
+     * @extension key1 ["v1","v2"]
+     * @extension key2 {"x":"v1", "y":"v2"}
+     * @tag test
+     * @author cqmike
+     * @return
+     */
+    @GetMapping("configQueryParamGet")
+    public void configQueryParamGet(String configQueryParam) {
+
+    }
+}
+```
+it will output extension tags in openapi.json:
+```
+{
+  "paths":{
+    "/xxx/xxx": {
+      "post": {
+        "summary": "xxx",
+        "tags": [
+          ...
+        ],
+        "requestBody": {
+          ...
+        },
+        "responses": {
+        ...
+        },
+        "operationId": "xxx-POST",
+        "x-group": "ecs",
+        "x-key1": ["v1","v2"],
+        "x-key2": {"x":"v1", "y":"v2"},
+        "parameters": [
+             ...
+        ]
+      }
+    }
+  }
+}
+```
+
 
 # IDEA custom tag prompt
 The custom tag is not automatically prompted by default, and requires the user to set it in the idea. You can use it after setting it up. The following takes the setting of smart-doc custom mock tag as an example. The setting operation is as follows:

diff --git a/docs/zh-cn/start/guide.md b/docs/zh-cn/start/guide.md
@@ -149,20 +149,21 @@ public interface DubboInterface {
 使用介绍如下：
 
 
-| tag                                 | 描述                                                                                                                     | since   |
-|-------------------------------------|------------------------------------------------------------------------------------------------------------------------|---------|
+| tag                                 | 描述                                                                                                                   | since   |
+|-------------------------------------|----------------------------------------------------------------------------------------------------------------------|---------|
 | [`@ignore`](#_1-ignore)             | `@ignore` 如果`@ignore`加到方法上，则接口方法不会输出到文档。从`1.8.4`开始`@ignore`支持添加到`Controller`上进行忽略不想生成文档的接口类。`@ignore`也可以用于方法上忽略某个请求参数。 | -       |
-| [`@mock`](#_2-mock)                 | `@mock` `tag`用于在对象基本类型字段设置自定义文档展示值。设置值后`smart-doc`不再帮你生成随机值。方便可以通过`smart-doc`直接输出交付文档。                                 | `1.8.0` |
-| `@dubbo`                            | `@dubbo` `tag`用于在`Dubbo`的`API`接口类上添加让`smart-doc`可以扫描到`Dubbo RPC`的接口生成文档。                                               | `1.8.7` |
-| `@restApi`                          | `@restApi` `tag`用于支持`smart-doc`去扫描`Spring Cloud Feign`的定义接口生成文档。                                                       | `1.8.8` |
-| `@order`                            | `@order` `tag`用于设置`Controller`接口或者`API`入口的自定义排序序号，`@order 1`就表示设置序号为`1`。                                               | `1.9.4` |
-| `@ignoreResponseBodyAdvice`         | `@ignoreResponseBodyAdvice` `tag`用于忽略`ResponseBodyAdvice`设置的包装类。                                                       | `1.9.8` |
-| [`@download`](#_3-download)         | `@download` `tag`用于标注在`Controller`的文件下载方法上，生成`debug`页面时可实现文件下载测试。并且支持下载文件带请求头参数测试。                                     | `2.0.1` |
-| [`@page`](#_4-page)                 | `@page` `tag`用于标注在`Controller`的方法上表示该方法用来渲染返回一个静态页面，生成`debug`页面时如果发起测试，测试页面会自动在浏览器开启新标签显示页面。                           | `2.0.2` |
-| [`@ignoreParams`](#_5-ignoreparams) | `@ignoreParams` `tag`用于标注在`Controller`方法上忽略掉不想显示在文档中的参数，例如：`@ignoreParams id name`，多个参数名用空格隔开                          | `2.1.0` |
-| [`@response`(不推荐)](#_6-response不推荐) | `@response` `tag`标注在`Controller`方法上可以允许用这自己定义返回的`json example`。建议只在返回基础类型时使用，如：`Result<String>`类型这种泛型是简单原生类型的响应。       | `2.2.0` |
-| [`@service`](#_7-service)           | `@service` `tag`用于标注`Dubbo`的`API`接口的服务名称。                                                                              | `3.0.1` |
-| [`@protocol`](#_8-protocol)         | `@protocol` `tag`用于标注`Dubbo`的`API`接口的协议类型。                                                                             | `3.0.1` |
+| [`@mock`](#_2-mock)                 | `@mock` `tag`用于在对象基本类型字段设置自定义文档展示值。设置值后`smart-doc`不再帮你生成随机值。方便可以通过`smart-doc`直接输出交付文档。                               | `1.8.0` |
+| `@dubbo`                            | `@dubbo` `tag`用于在`Dubbo`的`API`接口类上添加让`smart-doc`可以扫描到`Dubbo RPC`的接口生成文档。                                             | `1.8.7` |
+| `@restApi`                          | `@restApi` `tag`用于支持`smart-doc`去扫描`Spring Cloud Feign`的定义接口生成文档。                                                     | `1.8.8` |
+| `@order`                            | `@order` `tag`用于设置`Controller`接口或者`API`入口的自定义排序序号，`@order 1`就表示设置序号为`1`。                                             | `1.9.4` |
+| `@ignoreResponseBodyAdvice`         | `@ignoreResponseBodyAdvice` `tag`用于忽略`ResponseBodyAdvice`设置的包装类。                                                     | `1.9.8` |
+| [`@download`](#_3-download)         | `@download` `tag`用于标注在`Controller`的文件下载方法上，生成`debug`页面时可实现文件下载测试。并且支持下载文件带请求头参数测试。                                   | `2.0.1` |
+| [`@page`](#_4-page)                 | `@page` `tag`用于标注在`Controller`的方法上表示该方法用来渲染返回一个静态页面，生成`debug`页面时如果发起测试，测试页面会自动在浏览器开启新标签显示页面。                         | `2.0.2` |
+| [`@ignoreParams`](#_5-ignoreparams) | `@ignoreParams` `tag`用于标注在`Controller`方法上忽略掉不想显示在文档中的参数，例如：`@ignoreParams id name`，多个参数名用空格隔开                        | `2.1.0` |
+| [`@response`(不推荐)](#_6-response不推荐) | `@response` `tag`标注在`Controller`方法上可以允许用这自己定义返回的`json example`。建议只在返回基础类型时使用，如：`Result<String>`类型这种泛型是简单原生类型的响应。     | `2.2.0` |
+| [`@service`](#_7-service)           | `@service` `tag`用于标注`Dubbo`的`API`接口的服务名称。                                                                            | `3.0.1` |
+| [`@protocol`](#_8-protocol)         | `@protocol` `tag`用于标注`Dubbo`的`API`接口的协议类型。                                                                           | `3.0.1` |
+| [`@extension`](#_9-extension)       | `@extension` `tag` 用于对openapi扩展能力 的支持。                                                                               | `3.0.3` |
 
 > 以上的一些自定义tag，我们建议国内的同学认真阅读这部分全部文档。包括后面对于一些tag的使用当中官方也给 了文字提示，不要去乱用。也不要觉得可以说服官方能够对当前的一些自定义tag做丰富。 首先我们是一个非常尊重编码规范的工具，我们不会去随便乱加一个东西来误导人，当前主流框架不提供的东西，我们不会在提供， 以后对tag的使用只会更加谨慎。
 
@@ -403,6 +404,60 @@ public interface DubboInterface {
   String sayHello(String word);
 }
 ```
+### 9. `@extension`
+@extension标记在controller method上. 用于支持OpenApi的扩展属性，它将在openapi.json中添加对应的"x-*"属性
+```java
+/**
+ * json file config test
+ * @tag dev
+ * @author cqmike 2021-07-16 14:09
+ **/
+@RestController
+public class ConfigRequestParamController {
+
+    /**
+     * get request test query param
+     * @extension group ecs
+     * @extension key1 ["v1","v2"]
+     * @extension key2 {"x":"v1", "y":"v2"}
+     * @tag test
+     * @author cqmike
+     * @return
+     */
+    @GetMapping("configQueryParamGet")
+    public void configQueryParamGet(String configQueryParam) {
+
+    }
+}
+```
+it will output extension tags in openapi.json:
+```
+{
+  "paths":{
+    "/xxx/xxx": {
+      "post": {
+        "summary": "xxx",
+        "tags": [
+          ...
+        ],
+        "requestBody": {
+          ...
+        },
+        "responses": {
+        ...
+        },
+        "operationId": "xxx-POST",
+        "x-group": "ecs",
+        "x-key1": ["v1","v2"],
+        "x-key2": {"x":"v1", "y":"v2"},
+        "parameters": [
+             ...
+        ]
+      }
+    }
+  }
+}
+```
 
 
 ## jsr参数验证