You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@servicecomb.apache.org by li...@apache.org on 2020/06/23 03:15:18 UTC
[servicecomb-java-chassis] branch master updated: [SCB-2020]support
@Example to add examples to API
This is an automated email from the ASF dual-hosted git repository.
liubao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/servicecomb-java-chassis.git
The following commit(s) were added to refs/heads/master by this push:
new 2b4c904 [SCB-2020]support @Example to add examples to API
2b4c904 is described below
commit 2b4c904a662406f5c09dc439910031fcad0693a2
Author: liubao <bi...@qq.com>
AuthorDate: Mon Jun 22 17:23:16 2020 +0800
[SCB-2020]support @Example to add examples to API
---
.../springmvc/client/ConsumerTestsAfterBootup.java | 29 +++++++++++-
.../demo/springmvc/client/SpringMVCSchema.java | 46 ++++++++++++++++++
.../src/main/resources/SpringMVCSchema.yaml | 54 ++++++++++++++++++++++
.../core/processor/annotation/AnnotationUtils.java | 20 +++++++-
.../annotation/models/ResponseConfig.java | 11 +++++
5 files changed, 158 insertions(+), 2 deletions(-)
diff --git a/demo/demo-springmvc/springmvc-client/src/main/java/org/apache/servicecomb/demo/springmvc/client/ConsumerTestsAfterBootup.java b/demo/demo-springmvc/springmvc-client/src/main/java/org/apache/servicecomb/demo/springmvc/client/ConsumerTestsAfterBootup.java
index efd3f18..1624a21 100644
--- a/demo/demo-springmvc/springmvc-client/src/main/java/org/apache/servicecomb/demo/springmvc/client/ConsumerTestsAfterBootup.java
+++ b/demo/demo-springmvc/springmvc-client/src/main/java/org/apache/servicecomb/demo/springmvc/client/ConsumerTestsAfterBootup.java
@@ -16,6 +16,10 @@ package org.apache.servicecomb.demo.springmvc.client;
* limitations under the License.
*/
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.Charset;
+
import org.apache.servicecomb.core.BootListener;
import org.apache.servicecomb.demo.TestMgr;
import org.apache.servicecomb.registry.RegistrationManager;
@@ -26,14 +30,37 @@ import org.springframework.stereotype.Component;
*/
@Component
public class ConsumerTestsAfterBootup implements BootListener {
- public void testRegisterPath() {
+ private void testRegisterPath() {
TestMgr.check(RegistrationManager.INSTANCE.getMicroservice().getPaths().size(), 0);
}
+ private void testSchemaContent() {
+ String content = RegistrationManager.INSTANCE.getMicroservice().getSchemaMap().get("SpringMVCSchema");
+ TestMgr.check(content.replaceAll("\\s", ""),
+ readFile("SpringMVCSchema.yaml").replaceAll("[\\s#]", ""));
+ }
+
+ private String readFile(String restController) {
+ // test code, make simple
+ try {
+ InputStream inputStream = this.getClass().getResource("/" + restController).openStream();
+ byte[] buffer = new byte[2048 * 10];
+ inputStream.skip(1000);
+ int len = inputStream.read(buffer);
+ TestMgr.check(2048 * 10 > len, true);
+ inputStream.close();
+ return new String(buffer, 0, len, Charset.forName("UTF-8"));
+ } catch (IOException e) {
+ TestMgr.failed(e.getMessage(), e);
+ return null;
+ }
+ }
+
@Override
public void onBootEvent(BootEvent event) {
if (event.getEventType() == BootListener.EventType.AFTER_REGISTRY) {
testRegisterPath();
+ testSchemaContent();
if (!TestMgr.isSuccess()) {
TestMgr.summary();
throw new IllegalStateException("some tests are failed. ");
diff --git a/demo/demo-springmvc/springmvc-client/src/main/java/org/apache/servicecomb/demo/springmvc/client/SpringMVCSchema.java b/demo/demo-springmvc/springmvc-client/src/main/java/org/apache/servicecomb/demo/springmvc/client/SpringMVCSchema.java
new file mode 100644
index 0000000..a4c8523
--- /dev/null
+++ b/demo/demo-springmvc/springmvc-client/src/main/java/org/apache/servicecomb/demo/springmvc/client/SpringMVCSchema.java
@@ -0,0 +1,46 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.servicecomb.demo.springmvc.client;
+
+import javax.servlet.http.HttpServletRequest;
+
+import org.apache.servicecomb.provider.rest.common.RestSchema;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestMethod;
+
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
+import io.swagger.annotations.Example;
+import io.swagger.annotations.ExampleProperty;
+
+@RestSchema(schemaId = "SpringMVCSchema")
+@RequestMapping("/springMvcSchema")
+public class SpringMVCSchema {
+ @ApiResponses({
+ @ApiResponse(code = 200, response = String.class, message = "success",
+ examples = @Example({
+ @ExampleProperty(value = "wget http://localhost/springMvcSchema/testApiExample", mediaType = "text"),
+ @ExampleProperty(value = "{name:hello}", mediaType = "application/json"),
+ @ExampleProperty(value = "{name:hello}", mediaType = "json")})
+ )})
+ @RequestMapping(path = "/testApiExample", method = RequestMethod.POST)
+ public String testApiExample(@RequestBody String name, HttpServletRequest request) {
+ return null;
+ }
+}
diff --git a/demo/demo-springmvc/springmvc-client/src/main/resources/SpringMVCSchema.yaml b/demo/demo-springmvc/springmvc-client/src/main/resources/SpringMVCSchema.yaml
new file mode 100644
index 0000000..6d80536
--- /dev/null
+++ b/demo/demo-springmvc/springmvc-client/src/main/resources/SpringMVCSchema.yaml
@@ -0,0 +1,54 @@
+## ---------------------------------------------------------------------------
+## Licensed to the Apache Software Foundation (ASF) under one or more
+## contributor license agreements. See the NOTICE file distributed with
+## this work for additional information regarding copyright ownership.
+## The ASF licenses this file to You under the Apache License, Version 2.0
+## (the "License"); you may not use this file except in compliance with
+## the License. You may obtain a copy of the License at
+##
+## http://www.apache.org/licenses/LICENSE-2.0
+##
+## Unless required by applicable law or agreed to in writing, software
+## distributed under the License is distributed on an "AS IS" BASIS,
+## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+## See the License for the specific language governing permissions and
+## limitations under the License.
+## ---------------------------------------------------------------------------
+
+################################################################################
+################################################################################
+################################################################################
+################################################################################
+
+---
+swagger: "2.0"
+info:
+ version: "1.0.0"
+ title: "swagger definition for org.apache.servicecomb.demo.springmvc.client.SpringMVCSchema"
+ x-java-interface: "gen.swagger.SpringMVCSchemaIntf"
+basePath: "/springMvcSchema"
+schemes:
+ - "http"
+consumes:
+ - "application/json"
+produces:
+ - "application/json"
+paths:
+ /testApiExample:
+ post:
+ operationId: "testApiExample"
+ parameters:
+ - in: "body"
+ name: "name"
+ required: true
+ schema:
+ type: "string"
+ responses:
+ "200":
+ description: "success"
+ examples:
+ text: "wget http://localhost/springMvcSchema/testApiExample"
+ application/json: "{name:hello}"
+ json: "{name:hello}"
+ schema:
+ type: "string"
diff --git a/swagger/swagger-generator/generator-core/src/main/java/org/apache/servicecomb/swagger/generator/core/processor/annotation/AnnotationUtils.java b/swagger/swagger-generator/generator-core/src/main/java/org/apache/servicecomb/swagger/generator/core/processor/annotation/AnnotationUtils.java
index 277a759..0f00b58 100644
--- a/swagger/swagger-generator/generator-core/src/main/java/org/apache/servicecomb/swagger/generator/core/processor/annotation/AnnotationUtils.java
+++ b/swagger/swagger-generator/generator-core/src/main/java/org/apache/servicecomb/swagger/generator/core/processor/annotation/AnnotationUtils.java
@@ -30,6 +30,7 @@ import org.apache.servicecomb.swagger.generator.core.processor.annotation.models
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ExampleProperty;
import io.swagger.annotations.ResponseHeader;
import io.swagger.converter.ModelConverters;
import io.swagger.models.Model;
@@ -79,6 +80,7 @@ public final class AnnotationUtils {
responseConfig.setResponseContainer(apiResponse.responseContainer());
responseConfig.setResponseReference(apiResponse.reference());
responseConfig.setResponseHeaders(apiResponse.responseHeaders());
+ responseConfig.setExamples(apiResponse.examples());
return responseConfig;
}
@@ -150,7 +152,7 @@ public final class AnnotationUtils {
response.setResponseSchema(model);
}
response.setDescription(responseConfig.getDescription());
-
+ addExamplesToResponse(response, responseConfig);
if (responseConfig.getResponseHeaders() != null) {
Map<String, Property> headers = generateResponseHeader(swagger, responseConfig.getResponseHeaders());
response.setHeaders(headers);
@@ -159,6 +161,22 @@ public final class AnnotationUtils {
responseConfig.setResponse(response);
}
+ private static void addExamplesToResponse(Response response, ResponseConfig responseConfig) {
+ if (responseConfig.getExamples() != null) {
+ for (ExampleProperty property : responseConfig.getExamples().value()) {
+ if (StringUtils.isEmpty(property.mediaType()) && StringUtils.isEmpty(property.value())) {
+ // @ApiResponse default value has one element, but type and value is empty.
+ // ignore this default value.
+ continue;
+ }
+ if (StringUtils.isEmpty(property.mediaType())) {
+ throw new IllegalStateException("media type is required in examples. e.g. 'text', 'json'.");
+ }
+ response.example(property.mediaType(), property.value());
+ }
+ }
+ }
+
private static Map<String, Property> generateResponseHeader(Swagger swagger,
List<ResponseHeaderConfig> responseHeaders) {
Map<String, Property> headers = new HashMap<>();
diff --git a/swagger/swagger-generator/generator-core/src/main/java/org/apache/servicecomb/swagger/generator/core/processor/annotation/models/ResponseConfig.java b/swagger/swagger-generator/generator-core/src/main/java/org/apache/servicecomb/swagger/generator/core/processor/annotation/models/ResponseConfig.java
index 2c2f992..64831e8 100644
--- a/swagger/swagger-generator/generator-core/src/main/java/org/apache/servicecomb/swagger/generator/core/processor/annotation/models/ResponseConfig.java
+++ b/swagger/swagger-generator/generator-core/src/main/java/org/apache/servicecomb/swagger/generator/core/processor/annotation/models/ResponseConfig.java
@@ -21,6 +21,7 @@ import java.util.List;
import org.apache.servicecomb.swagger.generator.core.processor.annotation.AnnotationUtils;
+import io.swagger.annotations.Example;
import io.swagger.annotations.ResponseHeader;
import io.swagger.models.Response;
@@ -36,6 +37,8 @@ public class ResponseConfig extends ResponseConfigBase {
// 根据本config生成的response
private Response response;
+ private Example examples;
+
public int getCode() {
return code;
}
@@ -69,4 +72,12 @@ public class ResponseConfig extends ResponseConfigBase {
public void setResponse(Response response) {
this.response = response;
}
+
+ public Example getExamples() {
+ return examples;
+ }
+
+ public void setExamples(Example examples) {
+ this.examples = examples;
+ }
}