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

Last change on this file since 125432 was 125432, checked in by Eric Lupinacci, 4 months ago

Création d'un nouveau type de service infrasubdivision pour permettre de gérer la nomenclature des infra subdivisions des pays.
Ajout des infra subdivisions de la france : communes et arrondisssements (pas de cantons pour l'instant).
  • Property svn:eol-style set to native
File size: 12.0 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: infrasubdivisions
35    description: Nomenclatures sur les infra subdivisions territoriales
36  - name: contours
37    description: Contours géographiques des territoires
38  - name: admin
39    description: Administration de l'API
40paths:
41  /continents:
42    get:
43      tags:
44        - continents
45      summary: Liste des continents
46      description: Renvoie la liste des continents au sens de geoIP
47      operationId: getContinents
48      responses:
49        '200':
50          $ref: '#/components/responses/continentSucces'
51  /zones:
52    get:
53      tags:
54        - zones
55      summary: Liste des zones du monde
56      description: Renvoie la liste complète des zones du monde selon UN M49
57      operationId: getZones
58      responses:
59        '200':
60          $ref: '#/components/responses/zoneSucces'
61  /pays:
62    get:
63      tags:
64        - pays
65      summary: Liste des pays
66      description: Renvoie la liste des pays filtrée ou pas
67      operationId: getListePays
68      parameters:
69        - name: continent
70          in: query
71          description: Le code geoIP du continent
72          required: false
73          schema:
74            $ref: '#/components/schemas/CodeGeoIP'
75        - name: zone
76          in: query
77          description: Le code UN M49 de la zone
78          required: false
79          schema:
80            $ref: '#/components/schemas/CodeNum3'
81          example: '002'
82      responses:
83        '200':
84          $ref: '#/components/responses/zoneSucces'
85        '400':
86          $ref: '#/components/responses/parametreErreur'
87  /pays/{codePays}:
88    get:
89      tags:
90        - pays
91      summary: Informations sur un pays
92      description: Renvoie toutes les informations disponibles sur un pays donné
93      operationId: getUnPays
94      parameters:
95        - name: codePays
96          in: path
97          description: Le code ISO 3166-1 alpha2 d'un pays
98          required: true
99          schema:
100            $ref: '#/components/schemas/CodeAlpha2'
101          example: 'FR'
102      responses:
103        '200':
104          $ref: '#/components/responses/zoneSucces'
105        '400':
106          $ref: '#/components/responses/ressourceErreur'
107  /subdivisions:
108    get:
109      tags:
110        - subdivisions
111      summary: Liste des subdivisions territoriales
112      description: Renvoie la liste des subdivisions filtrée ou pas
113      operationId: getSubdivisions
114      parameters:
115        - $ref: '#/components/parameters/paysParametre'
116        - name: type
117          in: query
118          description: Le type de subdivision au sens de l'ISO 3166-2
119          required: false
120          schema:
121            $ref: '#/components/schemas/Identifiant'
122        - name: exclure
123          in: query
124          description: liste des index à exclure de la réponse
125          required: false
126          schema:
127            type: string
128      responses:
129        '200':
130          $ref: '#/components/responses/zoneSucces'
131        '400':
132          $ref: '#/components/responses/parametreErreur'
133  /infrasubdivisions:
134    get:
135      tags:
136        - infrasubdivisions
137      summary: Liste des infra subdivisions territoriales
138      description: Renvoie la liste des infra subdivisions filtrée ou pas
139      operationId: getInfraSubdivisions
140      parameters:
141        - name: service
142          in: query
143          description: L'identifiant du service
144          required: true
145          schema:
146            $ref: '#/components/schemas/Identifiant'
147        - $ref: '#/components/parameters/paysParametre'
148        - name: type
149          in: query
150          description: Le type de subdivision au sens de l'ISO 3166-2
151          required: false
152          schema:
153            $ref: '#/components/schemas/Identifiant'
154        - name: exclure
155          in: query
156          description: liste des index à exclure de la réponse
157          required: false
158          schema:
159            type: string
160      responses:
161        '200':
162          $ref: '#/components/responses/zoneSucces'
163        '400':
164          $ref: '#/components/responses/parametreErreur'
165  /contours:
166    get:
167      tags:
168        - contours
169      summary: Liste des contours géographiques de territoires
170      description: Renvoie les contours géographiques fournis par un service géographique
171      operationId: getContours
172      parameters:
173        - name: type
174          in: query
175          description: Le type de territoire
176          required: true
177          schema:
178            type: string
179            enum: ['zone', 'country', 'subdivision']
180        - name: service
181          in: query
182          description: L'identifiant du service
183          required: true
184          schema:
185            $ref: '#/components/schemas/Identifiant'
186        - $ref: '#/components/parameters/paysParametre'
187      responses:
188        '200':
189          $ref: '#/components/responses/zoneSucces'
190        '400':
191          $ref: '#/components/responses/parametreErreur'
192  /services:
193    get:
194      tags:
195        - admin
196      summary: Liste des configurations des services de Nomenclatures
197      description: Renvoie la liste des configurations de service
198      operationId: getServices
199      parameters:
200        - name: type_service
201          in: query
202          description: Le type de service
203          required: false
204          schema:
205            type: string
206            enum: ['nomenclature', 'geometrie']
207      responses:
208        '200':
209          $ref: '#/components/responses/zoneSucces'
210components:
211  schemas:
212    CodeAlpha2:
213      type: string
214      pattern: '^[A-Z]{2}$'
215    CodeNum3:
216      type: string
217      pattern: '^[0-9]{3}$'
218    CodeGeoIP:
219      type: string
220      enum: ['AF', 'NA', 'OC', 'AN', 'AS', 'EU', 'SA']
221    Identifiant:
222      type: string
223      pattern: '^[a-z0-9_]+$'
224    IdentifiantMajuscule:
225      type: string
226      pattern: '^[A-Z0-9_]+$'
227    VersionSemantique:
228      type: string
229      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-]+)*))?$'
230    VersionSchemaBD:
231      type: string
232      pattern: '^[0-9.]+$'
233    MethodeHTTP:
234      type: string
235      enum: ['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'CONNECT', 'OPTIONS', 'TRACE']
236    BlocFournisseur:
237      type: object
238      properties:
239        plugin:
240          $ref: '#/components/schemas/IdentifiantMajuscule'
241        version:
242          $ref: '#/components/schemas/VersionSemantique'
243        schema:
244          $ref: '#/components/schemas/VersionSchemaBD'
245      required: ['plugin', 'version', 'schema']   
246    BlocRequete:
247      type: object
248      properties:
249        methode:
250          $ref: '#/components/schemas/MethodeHTTP'
251        format:
252          type: string
253          enum: ['ezrest']
254        collection:
255          $ref: '#/components/schemas/Identifiant'
256        ressource:
257          type: string
258        filtres:
259          type: object
260        format_contenu:
261          type: string
262          enum: ['json']
263      required: ['methode', 'format', 'collection', 'ressource', 'filtres', 'format_contenu']   
264    BlocErreur:
265      type: object
266      properties:
267        status:
268          type: integer
269        type:
270          $ref: '#/components/schemas/Identifiant'
271        element:
272          type: string
273        valeur:
274          type: string
275        titre:
276          type: string
277        detail:
278          type: string
279      required: ['status', 'type', 'element', 'valeur', 'titre', 'detail']   
280    BlocDonneesContinent:
281      type: object
282      properties:
283        continents:
284          type: array
285          items:
286            type: object
287            properties:
288              code:
289                $ref: '#/components/schemas/CodeAlpha2'
290              code_M49:
291                $ref: '#/components/schemas/CodeNum3'
292              nom:
293                type: string
294          example:
295            code: AS
296            code_num: '142'
297            nom: '<multi>[fr]Asie[en]Asia</multi>'
298    BlocDonneesZone:
299      type: object
300      properties:
301        zones:
302          type: array
303          items:
304            type: object
305            properties:
306              code_num:
307                $ref: '#/components/schemas/CodeNum3'
308              category:
309                type: string
310              parent:
311                $ref: '#/components/schemas/CodeNum3'
312              label:
313                type: string
314          example:
315            code_num: '002'
316            category: 'continent'
317            parent: '001'
318            label: '<multi>[fr]Afrique[en]Africa</multi>'
319        continents:
320          type: object
321          additionalProperties:
322            type: object
323            properties:
324              code:
325                $ref: '#/components/schemas/CodeAlpha2'
326              code_num:
327                $ref: '#/components/schemas/CodeNum3'
328              label:
329                type: string
330          example:
331            '142': {code: AS, code_num: '142', label: '<multi>[fr]Asie[en]Asia</multi>'}
332    BlocDonnees:
333      type: object
334  parameters:
335    paysParametre:
336      name: pays
337      in: query
338      required: false
339      description: Code ISO 3166-1 alpha2 d'un pays
340      schema:
341        $ref: '#/components/schemas/CodeAlpha2'
342  responses:
343    continentSucces:
344      description: la requête a été traitée avec succès
345      content:
346        application/json:
347          schema:
348            type: object
349            properties:
350              donnees:
351                $ref: '#/components/schemas/BlocDonneesContinent'
352              erreur:
353                $ref: '#/components/schemas/BlocErreur'
354              fournisseur:
355                $ref: '#/components/schemas/BlocFournisseur'
356              requete:
357                $ref: '#/components/schemas/BlocRequete'
358    zoneSucces:
359      description: la requête a été traitée avec succès
360      content:
361        application/json:
362          schema:
363            type: object
364            properties:
365              donnees:
366                $ref: '#/components/schemas/BlocDonneesZone'
367              erreur:
368                $ref: '#/components/schemas/BlocErreur'
369              fournisseur:
370                $ref: '#/components/schemas/BlocFournisseur'
371              requete:
372                $ref: '#/components/schemas/BlocRequete'
373    Succes:
374      description: la requête a été traitée avec succès
375      content:
376        application/json:
377          schema:
378            type: object
379            properties:
380              donnees:
381                $ref: '#/components/schemas/BlocDonneesZone'
382              erreur:
383                $ref: '#/components/schemas/BlocErreur'
384              fournisseur:
385                $ref: '#/components/schemas/BlocFournisseur'
386              requete:
387                $ref: '#/components/schemas/BlocRequete'
388    parametreErreur:
389      description: paramètre non supporté ou invalide (voir le bloc erreur)
390    ressourceErreur:
391      description: ressource non supportée ou invalide (voir le bloc erreur)
Note: See TracBrowser for help on using the repository browser.