-
-
Notifications
You must be signed in to change notification settings - Fork 115
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Rest API Doc out of date #1450
Comments
Hey! The full OpenAPI spec is described here. You can generate API spec from the json definition as you wish. If there's anything inconsistent or you're hitting errors, please specify such issues. 🤘🏻 |
But Yes! It has to be reviewed and fixed. |
Hi @JanCizmar, thanks for your answer. Thanks to the Swagger doc I have been able to better unserstand how the rest API looks. But unfortunately there are a couple of issues: Swagger codegen creates unusable clientI tried generating the client with swagger-codegen, but due to the auth method used the client, once instantiated is unusable as it fails with a no auth provided error of some sorts. I generated the lib with: java -jar swagger-codegen.jar generate -i swagger.json -l java -o tolgee-client-library-java -DhideGenerationTimestamp=true The library is generated just fine, and all assets seem to be created correctly, but when I instantiate the client with ApiClient apiClient = new ApiClient();
apiClient.setApiKey(System.getenv("API_KEY"));
apiClient.setBasePath(System.getenv("URL"));
LanguagesApi languagesApi = new LanguagesApi(apiClient);
PagedModelLanguageModel languageModel = languagesApi.getAll6(1, 50, null, null, null);
List<LanguageModel> languageModels = languageModel.getEmbedded().getLanguages();
languageModels.stream().peek(System.out::println); But the following error is thrown: Exception in thread "main" java.lang.RuntimeException: No API key authentication configured!
at com.my-thing.tolgee.library.ApiClient.setApiKey(ApiClient.java:309)
at com.my-thing.Main.main(Main.java:31) Line 31 is where I set the Api Key, i.e. Exporting translations works only when the api key is NOT providedThe route specified in the spec fails with an error (don't have the specific one, sorry), but ONLY when the api key is provided. I used the same route that the UI calls ( Sorry if I don't have too many details, if needed let me know and I can provide them |
Hey! The Anyway, we don't guarantee that our swagger docs work with specific codegen tools, so this is not an Tolgee issue. |
Yes, you are right that this error is thrown by Swagger (and the generated client), but it is due to how the swaggerfile has been specified. I have used this generator on multiple other projects and it works without any issues, so my suspects are with the double auth implemented in Tolgee (and the fact that Swagger can't really understand it). I believe that once the old method (with URL params) is taken out, the generator will create the correct client, and therefore this issue will be irrelevant. For now, I'll keep using my own client, but will reconsider once this gets fixed by either side. |
@pennal I had to make tweaks to the spec to get the auth working the way I wanted. For example, adding an API key globally for the internal API: Also, I've noticed that some of the secondary HTTP verbs of an endpoint can be missing parameters: Over time, the swagger spec has been needing less and less tweaks to get it to work with (in my case) OpenAPI generator, and I just use Git to track any modifications so that I can replay them when I download the spec again. It still saves a ton of time since it's 95% of the way there |
@jdimeo thanks for your input. As you said, the spec is 95% there but for me the auth part is blocking me and preventing me from using it properly. Hopefully this will be fixed in a future release! |
This issue is stale because it has been open for 30 days with no activity. |
This issue was closed because it has been inactive for 14 days since being marked as stale. |
I just pulled the latest API spec and many parameters are no longer required. This is a problem for "path" parameters Also, |
More generally, can the API specifications identify which version of Tolgee they relate to? they have always said |
Well, that probably happened, because we updated Spring and Spring OpenApi version. Can you please share which endpoints exactly contain these errors? Also, what do you mean by "OpenAPI spec validation fails"? Thanks! |
Here's the exact output from the OpenAPI generator (which code generates API clients in many languages from a spec).
Here's the command: https://openapi-generator.tech/docs/usage/#validate |
tolgee-sdk-07-48-54.patch |
Thanks! It's some sort of bug that the path is missing for some of the errors and warnings? |
Yes, if the spec validation fails, the client doesn't generate the code. So I have to manually keep patching the OpenAPI spec so that the client will generate so I can continue using the API (which is how I'm interacting with all Tolgee APIs so I get a full client in any language we need). |
I am trying to play with that locally, but it seems like the output is incomplete:
|
Huh strange that the path is not specified. I use it exclusively as the Maven/Gradle plugin. Here's my config FWIW <plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>6.5.0</version>
<configuration>
<generateApiTests>false</generateApiTests>
<generateModelTests>false</generateModelTests>
<generatorName>java</generatorName>
<library>jersey3</library>
<apiPackage>io.tolgee.api</apiPackage>
<modelPackage>io.tolgee.model</modelPackage>
<addCompileSourceRoot>true</addCompileSourceRoot>
<globalProperties>
<skipFormModel>false</skipFormModel>
</globalProperties>
<configOptions>
<title>${project.name}</title>
<sourceFolder>.</sourceFolder>
<implFolder>.</implFolder>
<dateLibrary>java8</dateLibrary>
<serializationLibrary>jackson</serializationLibrary>
<java8>true</java8>
</configOptions>
</configuration>
<executions>
<execution>
<id>main-api</id>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec>${spec-dir}/internal-v2.json</inputSpec>
</configuration>
</execution>
</executions>
</plugin> Note that my PR was accepted and will be released in 6.6.0 which was required to do avatar image uploads to Tolgee |
Well it looks like the API spec have got broken with this update of SpringDoc OpenApi: #1629 So I'll try to update it to the 1.7.0 or 2.1.0, and hopefully fix it. |
So updating to springdoc-openapi to 1.7.0 helped, which I did in #1679, so after it's released your problem will be partly solved.
|
This issue is stale because it has been open for 30 days with no activity. |
This is not stale. This past update only had 3 parameter fixes, which is great considering how much changed! |
@Martin005 is working on that. |
Hi,
I am trying to implement a simple import/export script to integrate Tolgee in a CI/CD workflow and I am constantly hitting errors with the API. The current documentation (especially around the fields and explanations of the parameters) is not consistent to what the code is doing behind the scenes.
I have currently started to sniff out the requests made by the UI since those seem to work, but this is not sustainable in the long run. An example is the
<host>/v2/projects
endpoint which is not in the Docs, but is heavily used by the UI.Also, would you consider allowing the export of the OpenAPI spec so a library (and the different DTOs) could be generated on the fly?
The text was updated successfully, but these errors were encountered: