source: spip-zone/_plugins_/isocode/trunk/ezrest/isocode_openapi.schema.yaml @ 125387

Last change on this file since 125387 was 125387, checked in by Eric Lupinacci, 6 months ago

Ajout d'un schema OpenAPI qui permet simplement de tester l'API REST sous PHPStorms avec le nouveau plugin proposé par l'éditeur

  • Property svn:eol-style set to native
File size: 9.8 KB
Line 
1openapi: 3.0.0
2info:
3  description: |
4    API du plugin Nomenclatures.  Cette API fournit de nombreuses collections
5    de nomenclatures sur les langues et les territoires ainsi que des
6    contours géographiques au format geoJSON.
7   
8    Certaines données fournies possèdent une licence à respecter. Cette licence est précisée dans un bloc credits.
9  version: 1.0.0-oas3
10  title: Swagger Nomenclatures
11  contact:
12    name: Eric Lupinacci
13    email: eric@smellup.net
14  license:
15    name: GPL pour le plugin Nomenclatures
16    url: 'http://www.gnu.org/licenses/gpl-3.0.html'
17externalDocs:
18  description: Documentation du plugin Nomenclatures
19  url: 'https://blog.smellup.net/ecrire/?exec=article&id_article=96'
20servers:
21  - url: 'https://contrib.spip.net/http.api/ezrest'
22    description: Serveur de production
23  - url: 'http://localhost/spiprest/http.api/ezrest'
24    description: Serveur de tests
25tags:
26  - name: continents
27    description: Nomenclatures et informations sur les continents
28  - name: zones
29    description: Nomenclatures et informations sur les zones du monde
30  - name: pays
31    description: Nomenclatures et informations sur les pays du monde
32  - name: subdivisions
33    description: Nomenclatures et informations sur les subdivisions territoriales
34  - name: contours
35    description: Contours géographiques des territoires
36  - name: admin
37    description: Administration de l'API
38paths:
39  /continents:
40    get:
41      tags:
42        - continents
43      summary: Liste des continents
44      description: Renvoie la liste des continents au sens de geoIP
45      operationId: getContinents
46      responses:
47        '200':
48          $ref: '#/components/responses/zoneSucces'
49  /zones:
50    get:
51      tags:
52        - zones
53      summary: Liste des zones du monde
54      description: Renvoie la liste complète des zones du monde selon UN M49
55      operationId: getZones
56      responses:
57        '200':
58          $ref: '#/components/responses/zoneSucces'
59  /pays:
60    get:
61      tags:
62        - pays
63      summary: Liste des pays
64      description: Renvoie la liste des pays filtrée ou pas
65      operationId: getListePays
66      parameters:
67        - name: continent
68          in: query
69          description: Le code geoIP du continent
70          required: false
71          schema:
72            $ref: '#/components/schemas/CodeAlpha2'
73        - name: zone
74          in: query
75          description: Le code UN M49 de la zone
76          required: false
77          schema:
78            $ref: '#/components/schemas/CodeNum3'
79      responses:
80        '200':
81          $ref: '#/components/responses/zoneSucces'
82        '400':
83          $ref: '#/components/responses/parametreErreur'
84  /pays/{codePays}:
85    get:
86      tags:
87        - pays
88      summary: Informations sur un pays
89      description: Renvoie toutes les informations disponibles sur un pays donné
90      operationId: getUnPays
91      parameters:
92        - name: codePays
93          in: path
94          description: Le code ISO 3166-1 alpha2 d'un pays
95          required: true
96          schema:
97            $ref: '#/components/schemas/CodeAlpha2'
98      responses:
99        '200':
100          $ref: '#/components/responses/zoneSucces'
101        '400':
102          $ref: '#/components/responses/ressourceErreur'
103  /subdivisions:
104    get:
105      tags:
106        - subdivisions
107      summary: Liste des subdivisions territoriales
108      description: Renvoie la liste des subdivisions filtrée ou pas
109      operationId: getSubdivisions
110      parameters:
111        - $ref: '#/components/parameters/paysParametre'
112        - name: type
113          in: query
114          description: Le type de subdivision au sens de l'ISO 3166-2
115          required: false
116          schema:
117            $ref: '#/components/schemas/Identifiant'
118        - name: exclure
119          in: query
120          description: liste des index à exclure de la réponse
121          required: false
122          schema:
123            type: string
124      responses:
125        '200':
126          $ref: '#/components/responses/zoneSucces'
127        '400':
128          $ref: '#/components/responses/parametreErreur'
129  /contours:
130    get:
131      tags:
132        - contours
133      summary: Liste des contours géographiques de territoires
134      description: Renvoie les contours géographiques fournis par un service géographique
135      operationId: getContours
136      parameters:
137        - name: type
138          in: query
139          description: Le type de territoire
140          required: true
141          schema:
142            type: string
143            enum:
144            - 'zone'
145            - 'country'
146            - 'subdivision'
147        - name: service
148          in: query
149          description: L'identifiant du service
150          required: true
151          schema:
152            $ref: '#/components/schemas/Identifiant'
153        - $ref: '#/components/parameters/paysParametre'
154      responses:
155        '200':
156          $ref: '#/components/responses/zoneSucces'
157        '400':
158          $ref: '#/components/responses/parametreErreur'
159  /services:
160    get:
161      tags:
162        - admin
163      summary: Liste des configurations des services de Nomenclatures
164      description: Renvoie la liste des configurations de service
165      operationId: getServices
166      parameters:
167        - name: type_service
168          in: query
169          description: Le type de service
170          required: false
171          schema:
172            type: string
173            enum:
174            - 'nomenclature'
175            - 'geometrie'
176      responses:
177        '200':
178          $ref: '#/components/responses/zoneSucces'
179components:
180  schemas:
181    CodeAlpha2:
182      type: string
183      pattern: '^[A-Z]{2}$'
184    CodeNum3:
185      type: string
186      pattern: '^[0-9]{3}$'
187    Identifiant:
188      type: string
189      pattern: '^[a-z0-9_]+$'
190    IdentifiantMajuscule:
191      type: string
192      pattern: '^[A-Z0-9_]+$'
193    VersionSemantique:
194      type: string
195      pattern: '^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'
196    VersionSchemaBD:
197      type: string
198      pattern: '^[0-9.]+$'
199    MethodeHTTP:
200      type: string
201      enum: ['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'CONNECT', 'OPTIONS', 'TRACE']
202    BlocFournisseur:
203      type: object
204      properties:
205        plugin:
206          $ref: '#/components/schemas/IdentifiantMajuscule'
207        version:
208          $ref: '#/components/schemas/VersionSemantique'
209        schema:
210          $ref: '#/components/schemas/VersionSchemaBD'
211      required: ['plugin', 'version', 'schema']   
212    BlocRequete:
213      type: object
214      properties:
215        methode:
216          $ref: '#/components/schemas/MethodeHTTP'
217        format:
218          type: string
219          enum: ['ezrest']
220        collection:
221          $ref: '#/components/schemas/Identifiant'
222        ressource:
223          type: string
224        filtres:
225          type: object
226        format_contenu:
227          type: string
228          enum: ['json']
229      required: ['methode', 'format', 'collection', 'ressource', 'filtres', 'format_contenu']   
230    BlocErreur:
231      type: object
232      properties:
233        status:
234          type: integer
235        type:
236          $ref: '#/components/schemas/Identifiant'
237        element:
238          type: string
239        valeur:
240          type: string
241        titre:
242          type: string
243        detail:
244          type: string
245      required: ['status', 'type', 'element', 'valeur', 'titre', 'detail']   
246    BlocDonneesZone:
247      type: object
248      properties:
249        zones:
250          type: array
251          items:
252            type: object
253            properties:
254              code_num:
255                $ref: '#/components/schemas/CodeNum3'
256              category:
257                type: string
258              parent:
259                $ref: '#/components/schemas/CodeNum3'
260              label:
261                type: string
262          example:
263            code_num: '002'
264            category: 'continent'
265            parent: '001'
266            label: '<multi>[fr]Afrique[en]Africa</multi>'
267        continents:
268          type: object
269          additionalProperties:
270            type: object
271            properties:
272              code:
273                $ref: '#/components/schemas/CodeAlpha2'
274              code_num:
275                $ref: '#/components/schemas/CodeNum3'
276              label:
277                type: string
278          example:
279            '142': {code: AS, code_num: '142', label: '<multi>[fr]Asie[en]Asia</multi>'} 
280    BlocDonnees:
281      type: object
282  parameters:
283    paysParametre:
284      name: pays
285      in: query
286      required: false
287      description: Code ISO 3166-1 alpha2 d'un pays
288      schema:
289        $ref: '#/components/schemas/CodeAlpha2'
290  responses:
291    zoneSucces:
292      description: la requête a été traitée avec succès
293      content:
294        application/json:
295          schema:
296            type: object
297            properties:
298              donnees:
299                $ref: '#/components/schemas/BlocDonneesZone'
300              erreur:
301                $ref: '#/components/schemas/BlocErreur'
302              fournisseur:
303                $ref: '#/components/schemas/BlocFournisseur'
304              requete:
305                $ref: '#/components/schemas/BlocRequete'
306    Succes:
307      description: la requête a été traitée avec succès
308      content:
309        application/json:
310          schema:
311            type: object
312            properties:
313              donnees:
314                $ref: '#/components/schemas/BlocDonneesZone'
315              erreur:
316                $ref: '#/components/schemas/BlocErreur'
317              fournisseur:
318                $ref: '#/components/schemas/BlocFournisseur'
319              requete:
320                $ref: '#/components/schemas/BlocRequete'
321    parametreErreur:
322      description: paramètre non supporté ou invalide (voir le bloc erreur)
323    ressourceErreur:
324      description: ressource non supportée ou invalide (voir le bloc erreur)
Note: See TracBrowser for help on using the repository browser.