io.swagger.v3.oas.models.ExternalDocumentation Java Examples

@Test(dataProvider = "data")
public void readExternalDocsObject(JsonNode rootNode) throws Exception {
    final OpenAPIDeserializer deserializer = new OpenAPIDeserializer();
    final SwaggerParseResult result = deserializer.deserialize(rootNode);

    Assert.assertNotNull(result);

    final OpenAPI openAPI = result.getOpenAPI();
    Assert.assertNotNull(openAPI);

    final ExternalDocumentation externalDocumentation = openAPI.getExternalDocs();
    Assert.assertNotNull(externalDocumentation);
    Assert.assertNotNull(externalDocumentation.getUrl());
    Assert.assertEquals(externalDocumentation.getUrl(),"http://swagger.io");

    Assert.assertNotNull(externalDocumentation.getDescription());
    Assert.assertEquals(externalDocumentation.getDescription(),"Find out more about Swagger");

}
 

static ExternalDocumentation mergeExternalDocumentation(ExternalDocumentation thisExternalDocumentation,
                                                        ExternalDocumentation thatExternalDocumentation) {
  if (thatExternalDocumentation == null) {
    return thisExternalDocumentation;
  }
  if (thisExternalDocumentation == null) {
    return thatExternalDocumentation;
  }
  if (thatExternalDocumentation.getDescription() != null) {
    thisExternalDocumentation.setDescription(thatExternalDocumentation.getDescription());
  }
  if (thatExternalDocumentation.getUrl() != null) {
    thisExternalDocumentation.setUrl(thatExternalDocumentation.getUrl());
  }
  if (thatExternalDocumentation.getExtensions() != null) {
    thisExternalDocumentation.setExtensions(thatExternalDocumentation.getExtensions());
  }
  return thisExternalDocumentation;
}
 

public Tag getTag(ObjectNode obj, String location, ParseResult result) {
    if (obj == null) {
        return null;
    }

    Tag tag = new Tag();

    String value = getString("name", obj, true, location, result);
    if(StringUtils.isNotBlank(value)) {
        tag.setName(value);
    }

    value = getString("description", obj, false, location, result);
    if(StringUtils.isNotBlank(value)) {
        tag.setDescription(value);
    }

    ObjectNode docs = getObject("externalDocs",obj,false,location,result);
    ExternalDocumentation externalDocs = getExternalDocs(docs, String.format("%s.%s", location, "externalDocs"), result);
    if (externalDocs != null) {
        tag.setExternalDocs(externalDocs);
    }

    Map <String,Object> extensions = getExtensions(obj);
    if(extensions != null && extensions.size() > 0) {
        tag.setExtensions(extensions);
    }

    Set<String> keys = getKeys(obj);
    for(String key : keys) {
        if(!TAG_KEYS.contains(key) && !key.startsWith("x-")) {
            result.extra(location, key, obj.get(key));
        }
    }

    return tag;
}
 

/**
 * Updates External documentation in OpenAPI
 *
 * @param openAPI    the API doc
 * @param apiDocInfo the service information
 */
protected void updateExternalDoc(OpenAPI openAPI, ApiDocInfo apiDocInfo) {
    if (apiDocInfo.getApiInfo() == null)
        return;

    String externalDocUrl = apiDocInfo.getApiInfo().getDocumentationUrl();

    if (externalDocUrl != null) {
        ExternalDocumentation externalDoc = new ExternalDocumentation();
        externalDoc.setDescription(EXTERNAL_DOCUMENTATION);
        externalDoc.setUrl(externalDocUrl);
        openAPI.setExternalDocs(externalDoc);
    }
}
 

private ExternalDocumentation convert(ExternalDocs externalDocs) {
    ExternalDocumentation externalDocumentation = new ExternalDocumentation();

    externalDocumentation.setUrl(externalDocs.getUrl());
    externalDocumentation.setDescription(externalDocs.getDescription());
    Map<String, Object> extensions = convert(externalDocs.getVendorExtensions());
    if (extensions != null && extensions.size() > 0) {
        externalDocumentation.setExtensions(extensions);
    }

    return externalDocumentation;
}
 

@Bean
public OpenAPI springShopOpenAPI() {
	return new OpenAPI()
			.info(new Info().title("SpringShop API").description("Spring shop sample application").version("v0.0.1")
					.license(new License().name("Apache 2.0").url("http://springdoc.org")))
			.externalDocs(new ExternalDocumentation().description("SpringShop Wiki Documentation")
					.url("https://springshop.wiki.github.org/docs"));
}
 

/**
 * Gets tag.
 *
 * @return the tag
 */
default Tag getTag() {
	Tag actuatorTag = new Tag();
	actuatorTag.setName(Constants.SPRINGDOC_ACTUATOR_TAG);
	actuatorTag.setDescription(Constants.SPRINGDOC_ACTUATOR_DESCRIPTION);
	actuatorTag.setExternalDocs(
			new ExternalDocumentation()
					.url(Constants.SPRINGDOC_ACTUATOR_DOC_URL)
					.description(Constants.SPRINGDOC_ACTUATOR_DOC_DESCRIPTION)
	);
	return actuatorTag;
}
 

@Override
public StructuralNode apply(StructuralNode node, Parameters params) {
    ExternalDocumentation externalDocs = params.externalDocs;
    if (externalDocs == null) return node;

    String url = externalDocs.getUrl();
    if (StringUtils.isNotBlank(url)) {
        Block paragraph = new ParagraphBlockImpl(node);
        String desc = externalDocs.getDescription();
        paragraph.setSource(url + (StringUtils.isNotBlank(desc) ? "[" + desc + "]" : ""));
        node.append(paragraph);
    }

    return node;
}
 

public StructuralNode apply(StructuralNode node, ExternalDocumentation externalDocs) {
    return apply(node, parameters(externalDocs));
}
 

public Operation getOperation(ObjectNode obj, String location, ParseResult result) {
    if (obj == null) {
        return null;
    }
    Operation operation = new Operation();

    ArrayNode array = getArray("tags", obj, false, location, result);
    List<String> tags = getTagsStrings(array, String.format("%s.%s", location, "tags"), result);
    if (tags != null) {
        operation.setTags(tags);
    }
    String value = getString("summary", obj, false, location, result);
    if (StringUtils.isNotBlank(value)) {
        operation.setSummary(value);
    }

    value = getString("description", obj, false, location, result);
    if (StringUtils.isNotBlank(value)) {
        operation.setDescription(value);
    }

    ObjectNode externalDocs = getObject("externalDocs", obj, false, location, result);
    ExternalDocumentation docs = getExternalDocs(externalDocs, String.format("%s.%s", location, "externalDocs"), result);
    if(docs != null) {
        operation.setExternalDocs(docs);
    }
    value = getString("operationId", obj, false, location, result, operationIDs);
    if (StringUtils.isNotBlank(value)) {
        operation.operationId(value);
    }

    ArrayNode parameters = getArray("parameters", obj, false, location, result);
    if (parameters != null){
        operation.setParameters(getParameterList(parameters, String.format("%s.%s", location, "parameters"), result));
    }

    final ObjectNode requestObjectNode = getObject("requestBody", obj, false, location, result);
    if (requestObjectNode != null){
        operation.setRequestBody(getRequestBody(requestObjectNode, String.format("%s.%s", location, "requestBody"), result));
    }

    ObjectNode responsesNode = getObject("responses", obj, true, location, result);
    ApiResponses responses = getResponses(responsesNode, String.format("%s.%s", location, "responses"), result, false);
    if(responses != null) {
        operation.setResponses(responses);
    }

    ObjectNode callbacksNode = getObject("callbacks", obj, false, location, result);
    Map<String,Callback> callbacks = getCallbacks(callbacksNode, String.format("%s.%s", location, "callbacks"), result, false);
    if(callbacks != null){
        operation.setCallbacks(callbacks);
    }

    Boolean deprecated = getBoolean("deprecated", obj, false, location, result);
    if (deprecated != null) {
        operation.setDeprecated(deprecated);
    }

    array = getArray("servers", obj, false, location, result);
    if (array != null && array.size() > 0) {
        operation.setServers(getServersList(array, String.format("%s.%s", location, "servers"), result));
    }


    array = getArray("security", obj, false, location, result);
    if (array != null) {
        operation.setSecurity(getSecurityRequirementsList(array, String.format("%s.%s", location, "security"), result));
    }


    Map <String,Object> extensions = getExtensions(obj);
    if(extensions != null && extensions.size() > 0) {
        operation.setExtensions(extensions);
    }

    Set<String> keys = getKeys(obj);
    for(String key : keys) {
        if(!OPERATION_KEYS.contains(key) && !key.startsWith("x-")) {
            result.extra(location, key, obj.get(key));
        }
    }


    return operation;
}
 

public OpenAPI parseRoot(JsonNode node, ParseResult result, String path) {
    String location = "";
    OpenAPI openAPI = new OpenAPI();
    if (node.getNodeType().equals(JsonNodeType.OBJECT)) {
        ObjectNode rootNode = (ObjectNode) node;

        // required
        String value = getString("openapi", rootNode, true, location, result);

        // we don't even try if the version isn't there
        if(value == null || !value.startsWith("3.0")) {
            return null;
        }
        openAPI.setOpenapi(value);

        ObjectNode obj = getObject("info", rootNode, true, location, result);
        if (obj != null) {
            Info info = getInfo(obj, "info", result);
            openAPI.setInfo(info);
        }

        obj = getObject("components", rootNode, false, location, result);
        if (obj != null) {
            Components components = getComponents(obj, "components", result);
            openAPI.setComponents(components);
            this.components=components;
        }

        obj = getObject("paths", rootNode, true, location, result);
        if (obj != null) {
            Paths paths = getPaths(obj, "paths", result);
            openAPI.setPaths(paths);
        }


        ArrayNode array = getArray("servers", rootNode, false, location, result);
        if (array != null && array.size() > 0) {
            openAPI.setServers(getServersList(array, String.format("%s.%s", location, "servers"), result, path));
        }else {
            Server defaultServer = new Server();
            defaultServer.setUrl("/");
            List<Server>  servers = new ArrayList<>();
            servers.add(defaultServer);
            openAPI.setServers(servers);
        }

        obj = getObject("externalDocs", rootNode, false, location, result);
        if (obj != null) {
            ExternalDocumentation externalDocs = getExternalDocs(obj, "externalDocs", result);
            openAPI.setExternalDocs(externalDocs);
        }

        array = getArray("tags", rootNode, false, location, result);
        if (array != null && array.size() > 0) {
            openAPI.setTags(getTagList(array, "tags", result));
        }

        array = getArray("security", rootNode, false, location, result);
        if (array != null && array.size() > 0) {
            List<SecurityRequirement> securityRequirements = getSecurityRequirementsList(array, "security", result);
            if (securityRequirements != null && securityRequirements. size() > 0) {
                openAPI.setSecurity(securityRequirements);
            }
        }

        Map <String,Object> extensions = getExtensions(rootNode);
        if(extensions != null && extensions.size() > 0) {
            openAPI.setExtensions(extensions);
        }

        Set<String> keys = getKeys(rootNode);
        for(String key : keys) {
            if(!ROOT_KEYS.contains(key) && !key.startsWith("x-")) {
                result.extra(location, key, node.get(key));
            }
        }

    } else {
        result.invalidType(location, "openapi", "object", node);
        result.invalid();
        return null;
    }

    return openAPI;
}
 

public InheritedModelEndpointTest() {
    super(Arrays.asList(InheritedModelEndpoint.class, Discriminator.class,
            Schema.class, ArraySchema.class, ExternalDocumentation.class,
            XML.class, Version.class));
}
 

public Parameters(ExternalDocumentation externalDocs) {
    this.externalDocs = externalDocs;
}
 

public static Parameters parameters(ExternalDocumentation externalDocs) {
    return new Parameters(externalDocs);
}
 

public void setExternalDocs(ExternalDocumentation externalDocs) {
    this.externalDocs = externalDocs;
}
 

public ExternalDocumentation getExternalDocs() {
    return externalDocs;
}
 

public void setExternalDocumentation(ExternalDocumentation externalDocumentation) {
    this.externalDocumentation = externalDocumentation;
}
 

public ExternalDocumentation getExternalDocumentation() {
    return externalDocumentation;
}
 

private static void createApiInfo(OpenAPI openAPI) {
    try (InputStream is = GenerateRestClients.class.getClassLoader().getResourceAsStream("META-INF/konduit-serving-clients-git.properties")) {
        if (is == null) {
            throw new IllegalStateException("Cannot find konduit-serving-clients-git.properties on classpath");
        }
        Properties gitProperties = new Properties();
        gitProperties.load(is);
        String projectVersion = gitProperties.getProperty("git.build.version");
        String commitId = gitProperties.getProperty("git.commit.id").substring(0, 8);

        openAPI.info(new Info()
                .title("Konduit Serving REST API")
                .version(String.format("%s | Commit: %s", projectVersion, commitId))
                .description("RESTful API for various operations inside konduit-serving")
                .license(new License()
                        .name("Apache 2.0")
                        .url("https://github.com/KonduitAI/konduit-serving/blob/master/LICENSE"))
                .contact(new Contact()
                        .url("https://konduit.ai/contact")
                        .name("Konduit K.K.")
                        .email("[email protected]")))
                .tags(Collections.singletonList(
                        new Tag()
                                .name("inference")
                                .description("Inference server operations")))
                .externalDocs(new ExternalDocumentation()
                        .description("Online documentation")
                        .url("https://serving.konduit.ai"))
                .path("/predict", new PathItem()
                        .summary("Predicts an output based on the given JSON (key/value) or binary string")
                        .description("Takes a JSON string of key value pairs or a binary data string (protobuf) as input " +
                                "and processes it in the pipeline. The output could be json or a binary string based on " +
                                "the accept header value (application/json or application/octet-stream respectively).")
                        .post(new Operation()
                                .operationId("predict")
                                .addTagsItem("inference")
                                .requestBody(new RequestBody()
                                        .required(true)
                                        .content(new Content()
                                                .addMediaType(APPLICATION_JSON.toString(),
                                                        new MediaType().schema(new MapSchema()))
                                                .addMediaType(APPLICATION_OCTET_STREAM.toString(),
                                                        new MediaType().schema(new BinarySchema()))
                                        )
                                ).responses(new ApiResponses()
                                        .addApiResponse("200", new ApiResponse()
                                                .description("Successful operation")
                                                .content(new Content()
                                                        .addMediaType(APPLICATION_JSON.toString(),
                                                                new MediaType().schema(new MapSchema()))
                                                        .addMediaType(APPLICATION_OCTET_STREAM.toString(),
                                                                new MediaType().schema(new BinarySchema()))
                                                )
                                        ).addApiResponse("500", new ApiResponse()
                                                .description("Internal server error")
                                                .content(new Content()
                                                        .addMediaType(APPLICATION_JSON.toString(), new MediaType()
                                                                .schema(new ObjectSchema().$ref("#/components/schemas/ErrorResponse"))
                                                        )
                                                )
                                        )
                                )
                        )
                );
    } catch (IOException e) {
        throw new IllegalStateException(e.getMessage());
    }
}