docs: add a basic description of the API, as a markdown file

openapi/DESCRIPTION.md

@@ -0,0 +1,35 @@
+## What is this?
+
+An _Application Programming Interface_ (API) for a polling application
+using **Majority Judgment**.
+
+You are looking at the specifications of the communication between server and clients, usually because you want to make your own client.
+
+### Help, I'm lost!
+
+Best head to the official application client, then:
+[Application MieuxVoter](https://app.mieuxvoter.fr).
+See you there !
+
+
+## What is Majority Judgment?
+
+We believe that it is the most elegant polling system that is available right now.
+
+It was discovered in 2002 by 🇫🇷 french researchers, and it comes from 🍷 wine 🏆 contests.
+
+
+## Contributing
+
+### I've found a bug!
+
+Head over to our [issues tracker](https://github.com/MieuxVoter/mv-api-spec/issues) with your ideas and contributions.
+
+### But I don't understand code!
+
+It's okay, we need everyone!
+There's lots you can do to help, such as translating, documenting, reporting issues, painting pixels, promoting majority judgment…
+
+### Shut up and take my money!
+
+Donations help us boost development : [Donate](https://mieuxvoter.fr/index.php/participer/).

openapi/mv-openapi-root.yaml

@@ -1,7 +1,8 @@
 openapi: 3.0.0
 info:
-  title: Mieux Voter
-  description: A poll application based on Majority Judgment.
+  title: API Mieux Voter
+  description:
+    $ref: 'DESCRIPTION.md'
   version: 1.0.1-oas3
   termsOfService: 'https://github.com/MieuxVoter'
   contact: