Add code example links to individual method documentation in API refs guide #6626
Conversation
| */ | ||
| private static String mapServiceNameToExampleKey(String serviceName) { | ||
| if (serviceName == null) { | ||
| return ""; |
There was a problem hiding this comment.
Question: in what scenario would service name be null?
There was a problem hiding this comment.
Hmm, the service name won't be null anytime, we don't need this check, removed it.
| return urlMap; | ||
| } | ||
|
|
||
| ObjectMapper objectMapper = new ObjectMapper(); |
There was a problem hiding this comment.
nit: create a constant since creating object mapper is expensive
| * @param operationName the name of the operation to find an example for | ||
| * @return a '@see also' HTML link to the code example, or empty string if no example found | ||
| */ | ||
| public static String createLinkToCodeExample(Metadata metadata, String operationName) { |
There was a problem hiding this comment.
Can we add some codegen tests? we can create a mock example.json file
| return String.format("<a href=\"%s\" target=\"_top\">Code Example</a>", url); | ||
| } | ||
|
|
||
| return ""; |
There was a problem hiding this comment.
Should we just use null to indicate there's no example, so here, we'd return Optional.empty()?
There was a problem hiding this comment.
Hmm, we're not using null here. we're returning an empty string ("") right, so based on the check we have in OperationDocProvider.java, it wont show example when its empty string.
| if (servicesNode != null) { | ||
| for (JsonNode serviceNode : servicesNode) { | ||
| JsonNode examplesNode = serviceNode.get("examples"); | ||
| if (examplesNode != null && examplesNode.isArray()) { | ||
| for (JsonNode example : examplesNode) { | ||
| JsonNode idNode = example.get("id"); | ||
| JsonNode urlNode = example.get("url"); | ||
|
|
||
| if (idNode != null && urlNode != null) { | ||
| String id = idNode.asText(); | ||
| String url = urlNode.asText(); | ||
| if (!id.isEmpty() && !url.isEmpty()) { | ||
| urlMap.put(id, url); | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
This is a bit hard to read, let's break up this a bit
There was a problem hiding this comment.
Sure, Updated it!
| return serviceName | ||
| .replaceAll("([a-z0-9])([A-Z])", "$1-$2") | ||
| .toLowerCase(Locale.ROOT); |
There was a problem hiding this comment.
Just to double check, if this the naming pattern example team has been using?
There was a problem hiding this comment.
Realized it was missing a few edge cases, so I refactored the code here a bit.
|
2 participants
Add code examples near the individual method documentation in Java SDK API Refs guide
Motivation and Context
Enhance the Java SDK API Refs documentation to include code examples.
Modifications
Added
createLinkToCodeExamplemethod toDocumentationUtils.javato generate code example links from example-meta.jsonUpdated
OperationDocProvider.javawhich is in codegen and responsible for generating Javadoc documentation for individual operation methods to include "Code Example" links in method @see sections, appearing after AWS API Documentation linksTesting
Screenshots (if appropriate)
Types of changes
Checklist
mvn installsucceedsscripts/new-changescript and following the instructions. Commit the new file created by the script in.changes/next-releasewith your changes.License