Describe the new API with Swagger file to generate documentation

[nicolasleger]

• New OpenFoodFacts API
• Swagger and online example

[teolemon]

@nicolasleger can you help on that ?

[teolemon]

https://github.com/jhthorsen/swagger2

[nicolasleger]

@teolemon Sorry I didn't have time right now, and not familiar with Perl. For speed, Swagger file can be manually written.

[teolemon]

So we need a decent knowledge of Perl to be able to generate it automatically.

[ghost]

My suggestion to tackle this:

• create an OpenAPI specification as single source of truth, specifying exactly how the OpenFoodFacts API should behave
• use Swagger Codegen to generate our server endpoints as well as client libraries, using our OpenAPI specification

This

• reduces work in regards of generating additional client libraries
• reduces errors caused by servers/clients not adhering to the API specification

As Swagger Codegen does not contain template files for generating a Perl Server, it would be a clever move for us to work on exactly that.
If we start creating a Swagger Codegen perl server generator now, we can make the generated server work exactly how we need it. There's an existing issue about that, suggesting a different server framework, but I think this choice could be discussed with the swagger codegen maintainers.

[ghost]

@teolemon What are your thoughts on that topic?

[aleene]

If this also allows to do a quality check on the api, it would be great.

[ghost]

the spec (left side) would be checked into git and we iterate on the API until it fit our needs. Any quality checks can then be done on this textual representation of the API. As server & client are generated from this spec, we have a guarantee that server & client both meet the specification and thus can properly communicate.

[teolemon]

Marina is working on this as part of Google's Season of Docs