Make it possible to add custom API documentation based on the deployment location #6355
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…eplacer. This enable us to use this in places where we do not want to inject environment variables.
Codecov ReportAttention: Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## dev-2.x #6355 +/- ##
=============================================
+ Coverage 69.85% 69.87% +0.02%
- Complexity 17926 17981 +55
=============================================
Files 2035 2039 +4
Lines 76508 76626 +118
Branches 7825 7835 +10
=============================================
+ Hits 53442 53541 +99
- Misses 20325 20339 +14
- Partials 2741 2746 +5 ☔ View full report in Codecov by Sentry. |
In the case used, we compare to GraphQL schemas.
t2gran
force-pushed
the
custom-doc-transmodel-api
branch
from
4de6666 to
0bf3c72
Compare
t2gran
force-pushed
the
custom-doc-transmodel-api
branch
from
1f4cae2 to
f2406e7
Compare
habrahamsson-skanetrafiken
requested review from
leonardehrenfried and
tkalvas
| List of available custom documentation profiles. A profile is used to inject custom | ||
| documentation like type and field description or a deprecated reason. | ||
|
|
||
| Currently, ONLY the Transmodel API support this feature. |
There was a problem hiding this comment.
Suggested change
| Currently, ONLY the Transmodel API support this feature. | |
| Currently, ONLY the Transmodel API supports this feature. |
| private final Map<String, String> textMap; | ||
|
|
||
| /** | ||
| * Pacakge local to be unit-testable |
There was a problem hiding this comment.
Suggested change
| * Pacakge local to be unit-testable | |
| * Package local to be unit-testable |
| throw new OtpAppException("Resource not found: %s", resource); | ||
| } | ||
| var props = new Properties(); | ||
| props.load(input); |
There was a problem hiding this comment.
This method assumes that the input stream is ISO-8869-1 since properties files used to be hardcoded to that encoding.
You need to wrap the input stream in a reader like this:
new InputStreamReader(input, "UTF-8")
| import java.util.function.BiFunction; | ||
|
|
||
| /** | ||
| * This is GraphQL visitor witch inject custom documentation on types and fields. |
There was a problem hiding this comment.
Suggested change
| * This is GraphQL visitor witch inject custom documentation on types and fields. | |
| * This is GraphQL visitor which injects custom documentation on types and fields. |
t2gran
added
the
bump serialization id
| import org.opentripplanner._support.text.TextAssertions; | ||
|
|
||
| /** | ||
| * This test read in a schema file, inject documentation and convert the |
There was a problem hiding this comment.
Suggested change
| * This test read in a schema file, inject documentation and convert the | |
| * This test reads in a schema file, injects documentation and convert the |
leonardehrenfried
requested changes
Jan 7, 2025
t2gran
removed
the
bump serialization id
tkalvas
approved these changes
Jan 8, 2025
| var fieldName = field.getName(); | ||
| var typeName = parent.getName(); | ||
|
|
||
| Optional<T> f1 = customDocumentation |
There was a problem hiding this comment.
Really nitpicking here, but shouldn't f1 and f2 be named the other way around? Now f2 is the preferred one. I don't know.
| * <p> | ||
| * Note! There is a bug in the Java GraphQL library. Existing deprecated reasons | ||
| * cannot be changed or replaced. This test adds test-cases for this, but excludes | ||
| * them from the expected result. If this is fixed in the GraphQL library, this |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR introduce a new configuration parameter to load a deployment specific properies file.
router-config.json
custom-documentation-entur.properties
Syntax properties file
Use:
<TypeName>[.<FieldName>].(description|deprecated)[.append]Examples
Replace the existing type description
Quay.description=The place for boarding/alighting a vehicleAppend to the existing type description
Quay.description.append=This is appendedReplace the existing field description
Quay.name.description=The name of a Quay is ...Append to the existing field description
Quay.name.description.append=(Source NSR)Insert deprecated reason. Due to a bug in the Java GraphQL lib, an existing deprecated reason cannot be updated, but it can be deprecated if not already marked. Deleting the reason from the schema, and adding it back using
the "default" TransmodelApiDocumentationProfile can be used as a workaround. The problem is reported to the Java GraphQL Prodject here: graphql-java/graphql-java#3786.
Quay.name.deprecated=This field is deprecated ...Issue
🟥 No isse exist for this.
Unit tests
✅ All new code have unit-tests
Documentation
✅ JavaDoc and user doc is added/updated.
Changelog
✅ This is a new feature
Bumping the serialization version id
🟥 Not needed