Chore – Add OpenAPI documentation

[alfonsomunozpomer]

The best thing would be to read openapi/README.md and give it a go to see that you can generate the docs and start the Swager UI server. I have changed several variables in Docker Compose to make things more flexible and less tied in to a specific directory layout in our host machines.

@upendrakumbham I’m very interested in your thoughts regarding this solution as compared to RestDocs, which you used in your API project.

@haideriqbal @lingyun1010 Please have a look at this since I’d like to document the whole application with this approach.

Accompanied by ebi-gene-expression-group/atlas-web-core#76.

[upendrakumbham]

LGTM! simple and nice with fewer dependencies.
In my view, each API documentation tools have pros and cons. So, we need to pick the right tool based on our targeted end-user.

@openapi:
Pros:

• We have Swagger UI to interact with REST API. End-user can play around with our API.
• Non-tech users also can reach API easily.

Cons:

• Need to change actual code base implementation for the documentation. In our case, our endpoint is 3 lines, but documentation annotations are around 15-20 lines. Documentation code is more than actual.

@RestDocs:
Pros:

• Generate Documentation through tests. So, we will not touch the codebase to generate API documentation.
• Whenever we change the code base, we will fix the broken test cases. So, documentation is always in synch with Rest API.
• Other Developers can go through the documentation and use API.

Cons:

• No UI to interact with APIs like Open API. So, this documentation may not be that user-friendly for non-tech users.

[upendrakumbham]

All looks good to me.

[alfonsomunozpomer]

I converted this PR to a draft in order to move this to RestDocs combined with https://github.com/ePages-de/restdocs-api-spec.