io.swagger.v3.oas.models.tags.Tag Java Examples

private OpenAPI createCompleteExample() {
    OpenAPI openAPI = new OpenAPI();
    openAPI.setInfo(new Info().title("Some title").description("Some description"));
    openAPI.setExternalDocs(new ExternalDocumentation().url("http://abcdef.com").description("a-description"));
    openAPI.setServers(Arrays.asList(
            new Server().url("http://www.server1.com").description("first server"),
            new Server().url("http://www.server2.com").description("second server")
        ));
    openAPI.setSecurity(Arrays.asList(
            new SecurityRequirement().addList("some_auth", Arrays.asList("write", "read"))
        ));
    openAPI.setTags(Arrays.asList(
            new Tag().name("tag1").description("some 1 description"),
            new Tag().name("tag2").description("some 2 description"),
            new Tag().name("tag3").description("some 3 description")
        ));
    openAPI.path("/ping/pong", new PathItem().get(new Operation()
            .description("Some description")
            .operationId("pingOp")
            .responses(new ApiResponses().addApiResponse("200", new ApiResponse().description("Ok")))));
    openAPI.components(new Components().addSchemas("SomeObject", new ObjectSchema().description("An Obj").addProperties("id", new StringSchema())));
    openAPI.setExtensions(new LinkedHashMap<>()); // required because swagger-core is using HashMap instead of LinkedHashMap internally.
    openAPI.addExtension("x-custom", "value1");
    openAPI.addExtension("x-other", "value2");
    return openAPI;
}
 

private OpenAPI getDummyOpenApiObject(List<Server> servers) {
    OpenAPI openAPI = new OpenAPI();
    openAPI.setPaths(new Paths());
    openAPI.setTags(new ArrayList<>());
    openAPI.setOpenapi("3.0.0");
    openAPI.setServers(servers);

    Info info = new Info();
    info.setTitle("API Catalog");
    info.setDescription("REST API for the API Catalog service which is a component of the API Mediation Layer. Use this API to retrieve information regarding catalog dashboard tiles, tile contents and its status, API documentation and status for the registered services.");
    info.setVersion("1.0.0");
    openAPI.setInfo(info);

    Tag tag = new Tag();
    tag.setName("API Catalog");
    tag.setDescription("Current state information");
    openAPI.getTags().add(tag);

    openAPI.getPaths().put("/api1", new PathItem());
    openAPI.getPaths().put("/api2", new PathItem());
    return openAPI;
}
 

@Test(dataProvider = "data")
public void readTagObject(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 List<Tag> Tag = openAPI.getTags();
    Assert.assertNotNull(Tag);
    Assert.assertNotNull(Tag.get(0));
    Assert.assertNotNull(Tag.get(0).getName());
    Assert.assertEquals(Tag.get(0).getName(),"pet");
    Assert.assertNotNull(Tag.get(0).getDescription());
    Assert.assertEquals(Tag.get(0).getDescription(),"Everything about your Pets");
    Assert.assertNotNull(Tag.get(0).getExternalDocs());

    Assert.assertNotNull(Tag.get(1));
    Assert.assertNotNull(Tag.get(1).getName());
    Assert.assertNotNull(Tag.get(1).getDescription());
    Assert.assertEquals(Tag.get(1).getName(),"store");
    Assert.assertEquals(Tag.get(1).getDescription(),"Access to Petstore orders");
}
 

public List<Tag> getTagList(ArrayNode obj, String location, ParseResult result) {
    if (obj == null) {
        return null;
    }
    List<Tag> tags = new ArrayList<>();
    Set<String> tagsTracker = new HashSet<>();
    for (JsonNode item : obj) {
        if (item.getNodeType().equals(JsonNodeType.OBJECT)) {
            Tag tag = getTag((ObjectNode) item, location, result);
            if (tag != null) {
                tags.add(tag);

                if(tagsTracker.contains((String)tag.getName())) {
                    result.uniqueTags(location,tag.getName());
                }

                tagsTracker.add(tag.getName());
            }
        }
    }
    return tags;
}
 

private List<Tag> convertTags(List<io.swagger.models.Tag> v2tags) {
    List<Tag> v3tags = new ArrayList<>();

    for (io.swagger.models.Tag v2tag : v2tags) {
        Tag v3tag = new Tag();

        v3tag.setDescription(v2tag.getDescription());
        v3tag.setName(v2tag.getName());

        if (v2tag.getExternalDocs() != null) {
            v3tag.setExternalDocs(convert(v2tag.getExternalDocs()));
        }

        Map<String, Object> extensions = convert(v2tag.getVendorExtensions());
        if (extensions != null) {
            v3tag.setExtensions(extensions);
        }
        v3tags.add(v3tag);
    }

    return v3tags;
}
 

@Override
public Document apply(Document document, TagsComponent.Parameters parameters) {
    List<Tag> openAPITags = parameters.tags;
    if (null == openAPITags || openAPITags.isEmpty()) return document;

    Section tagsSection = new SectionImpl(document);
    tagsSection.setTitle(labels.getLabel(SECTION_TITLE_TAGS));

    DescriptionListImpl tagsList = new DescriptionListImpl(tagsSection);
    openAPITags.forEach(tag -> {
        DescriptionListEntryImpl tagEntry = new DescriptionListEntryImpl(tagsList, Collections.singletonList(new ListItemImpl(tagsList, tag.getName())));
        String description = tag.getDescription();
        if(StringUtils.isNotBlank(description)){
            ListItemImpl tagDesc = new ListItemImpl(tagEntry, "");
            tagDesc.setSource(description);
            externalDocumentationComponent.apply(tagDesc, tag.getExternalDocs());
            tagEntry.setDescription(tagDesc);
        }
        tagsList.addEntry(tagEntry);
    });

    tagsSection.append(tagsList);
    document.append(tagsSection);
    return document;
}
 

@Override
public OpenAPI handle(OpenAPI swagger) {
    if (swagger.getTags() == null) return swagger;

    for (Tag tag : swagger.getTags())
    {
        String newTagName = TextUtils.getFirstLine(tag.getDescription());

        swagger.getPaths().values().forEach(path -> {
            handleOperation(tag, newTagName, path.getGet());
            handleOperation(tag, newTagName, path.getPost());
            handleOperation(tag, newTagName, path.getPut());
            handleOperation(tag, newTagName, path.getDelete());
            handleOperation(tag, newTagName, path.getHead());
            handleOperation(tag, newTagName, path.getOptions());
            handleOperation(tag, newTagName, path.getPatch());
        });

        tag.setName(newTagName);
    }
    return swagger;
}
 

private void convertTag(RootModel rootModel, OpenAPI openApi) {
    for (var controller : rootModel.getControllers()) {
        var tag = new Tag();
        tag.setName(getTagName(controller));
        if (!_config.isResolveJavaDocAsTypeName())
            tag.setDescription(controller.getDescription());
        openApi.addTagsItem(tag);
    }
}
 

private void handleOperation(Tag tag, String newTagName, Operation operation) {
    if (operation == null) return;
    if (operation.getTags().contains(tag.getName()))
    {
        operation.getTags().remove(tag.getName());
        operation.getTags().add(newTagName);
    }
}
 

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;
}
 

/**
 * 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;
}
 

@Test(description = "Extensions in External Docs")
public void testIssue12() throws Exception {
    OpenAPI oas = getConvertedOpenAPIFromJsonFile(PET_STORE_JSON);
    for (Tag tag : oas.getTags()) {
        if (tag.getExternalDocs() != null) {
            assertNull(tag.getExternalDocs().getExtensions());
        }
    }
}
 

@Test(description = "Tags are missing in the converted spec")
public void testIssue5() throws Exception {
    OpenAPI oas = getConvertedOpenAPIFromJsonFile(PET_STORE_JSON);
    //Global Tags
    List<Tag> tags = oas.getTags();
    assertNotNull(tags);
    assertEquals(PET_TAG, tags.get(0).getName());
    //Operation Tag
    Operation petPut = oas.getPaths().get(PET_PATH).getPut();
    assertNotNull(petPut.getTags());
    assertEquals(PET_TAG, petPut.getTags().get(0));
}
 

private List<Tag> mapTagNameWithPath(OpenAPI openAPI,
        Map<String, String> tagNameFilePathMap) {
    return openAPI.getTags().stream().peek(tag -> {
        if (tag.getExtensions() != null) {
            tagNameFilePathMap.put(tag.getName(), (String) tag
                    .getExtensions()
                    .get(OpenApiObjectGenerator.EXTENSION_VAADIN_FILE_PATH));
            tag.getExtensions().remove(
                    OpenApiObjectGenerator.EXTENSION_VAADIN_FILE_PATH);
        }
    }).collect(Collectors.toList());
}
 

private void removeAndCompareFilePathExtensionInTags(OpenAPI generated,
        OpenAPI expected) {
    Map<String, String> generatedFilePath = new HashMap<>();
    List<Tag> newTagsWithoutFilePath = mapTagNameWithPath(generated,
            generatedFilePath);
    generated.setTags(newTagsWithoutFilePath);

    Map<String, String> expectedFilePath = new HashMap<>();
    List<Tag> expectedTagsWithoutFilePath = mapTagNameWithPath(expected,
            expectedFilePath);
    expected.setTags(expectedTagsWithoutFilePath);

    for (Map.Entry<String, String> generatedEntrySet : generatedFilePath
            .entrySet()) {
        String value = generatedEntrySet.getValue();
        String key = generatedEntrySet.getKey();
        boolean isBothNull = value == null
                && expectedFilePath.get(key) == null;
        String errorMessage = String.format(
                "File path doesn't match for tag '%s'",
                key);
        String ending = expectedFilePath.get(key).replace('/',
                File.separatorChar);
        Assert.assertTrue(errorMessage,
                isBothNull || (value != null && value.endsWith(ending)));
    }
}
 

private void sortTagsAndSchemas(OpenAPI api) {
    // sort tags
    api.getTags().sort(Comparator.comparing(Tag::getName));
    // sort component schemas
    api.getComponents()
            .setSchemas(new TreeMap<>(api.getComponents().getSchemas()));
}
 

private void setVaadinFilePath(Map<String, Object> objs, Tag tag) {
    if (tag.getExtensions() != null && tag.getExtensions().get(
            OpenApiObjectGenerator.EXTENSION_VAADIN_FILE_PATH) != null) {
        objs.put(VAADIN_FILE_PATH, tag.getExtensions()
                .get(OpenApiObjectGenerator.EXTENSION_VAADIN_FILE_PATH));
    }
}
 

private void addTagsInformation() {
    for (Map.Entry<ClassOrInterfaceDeclaration, String> endpointJavadoc : endpointsJavadoc
            .entrySet()) {
        Tag tag = new Tag();
        ClassOrInterfaceDeclaration endpointDeclaration = endpointJavadoc
                .getKey();
        String simpleClassName = endpointDeclaration.getNameAsString();
        tag.name(simpleClassName);
        tag.description(endpointJavadoc.getValue());
        tag.addExtension(EXTENSION_VAADIN_FILE_PATH,
                qualifiedNameToPath.get(endpointDeclaration
                        .getFullyQualifiedName().orElse(simpleClassName)));
        openApiModel.addTagsItem(tag);
    }
}
 

@Override
public List<OasViolation> validate(OasValidationContext context, OasObjectPropertyLocation location, Tag tag) {

  if (!isMatchCase(expectedCase, tag.getName())) {
    return singletonList(new OasViolation(location.property("name"), ERROR + expectedCase));
  }
  return emptyList();
}
 

@Override
protected String get$ref(Tag oasObject) {
  return null;
}
 

@Override
protected String getPropertyObject(Tag oasObject) {
  return oasObject.getDescription();
}
 

@Override
public void preprocessOpenAPI(OpenAPI openAPI) {
    super.processOpenAPI(openAPI);
    List<Tag> openAPITags = openAPI.getTags();
    this.tags = openAPITags != null ? openAPITags : Collections.emptyList();
}
 

public Parameters(List<Tag> tags) {
    this.tags = tags;
}
 

public Document apply(Document document, List<Tag> tags) {
    return apply(document, parameters(tags));
}
 

public static TagsComponent.Parameters parameters(List<Tag> tags) {
    return new TagsComponent.Parameters(tags);
}
 

public List<Tag> getTags() {
    return tags;
}
 

public Set<String> getGlobalTagNames(OpenAPI openAPI) {
  if (CollectionUtils.isEmpty(openAPI.getTags())) {
    return emptySet();
  }
  return openAPI.getTags().stream().map(Tag::getName).collect(toSet());
}
 

private boolean isHidden(List<Tag> tags) {
    return tags != null && tags.stream().anyMatch(tag -> tag.getName().equals(HIDDEN_TAG));
}
 

protected List<Tag> getTags() {
    List<Tag> tagList = Lists.newArrayList();
    return null;
}
 

@Override
protected List<Tag> getListProperty(OpenAPI oasObject) {
  return oasObject.getTags();
}