Mismatch Between OpenAPI Specifications in the Documentation and the Repository

[DKierner]

There seems to be a mismatch between the OpenAPI specification that is supplied in the documentation and the repository.
Look at these links:

• https://raw.githubusercontent.com/InterNetX/internetx-swagger-files/master/src/domainrobot.json
• https://raw.githubusercontent.com/InterNetX/js-domainrobot-sdk/master/src/swagger/domainrobot.json

The latest commit does not update the OpenAPI specification and the updated OpenAPI spec differs from the latest commit. At least, that is what is visible in the error logs shown in InterNetX/js-domainrobot-sdk#112.
As the OpenAPI specifications are generated files, it might be better to remove it from the code repository and add them to .gitignore, if saving them to the JavaScript SDK repository was not intended.

Mirrored issue: InterNetX/js-domainrobot-sdk#113

[Ephenodrom]

@DKierner Hello and thank you for the issue. The OpenAPI Docs are currently a bit out of sync, but that should not be a problem as there were no bigger changes in the API. We are currently reviewing how we can provide the API documentation and keep it as up-to-date as possible. I will inform the collegue who is responsible for the js SDK to take a look.

[DKierner]

@Ephenodrom Typically, your API server would document the ReST endpoints automatically via code statements and under a designated Swagger and Swagger UI endpoint (example: /api-docs<.json,.yaml>, /swagger-ui/index.html), making the separate manual generation of an OpenAPI specification redundant. See oatpp/oatpp-swagger or Documenting a Spring REST API Using OpenAPI 3.0 for examples.
I find it a bit odd that InterNetX opted for the manual generation.

[Ephenodrom]

@DKierner
Yes this the well known way to do it and also the target picture for us. As always, the software behind the API has grown historically and therefore there is still some work to do to be up to date in every aspect.