From 7ad95cff23247affa29fda3318562f49aab74065 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=A9my=20Rialland?= Date: Tue, 7 Jun 2022 14:10:48 +0200 Subject: [PATCH] Add documentation about api --- api/source/openapi.yaml | 7 +- .../test-e2e/__snapshots__/index.test.ts.snap | 7 +- site/source/pages/integration/API.tsx | 157 ++++++------------ 3 files changed, 62 insertions(+), 109 deletions(-) diff --git a/api/source/openapi.yaml b/api/source/openapi.yaml index 649febba6..52dcc1127 100644 --- a/api/source/openapi.yaml +++ b/api/source/openapi.yaml @@ -3,9 +3,12 @@ openapi: 3.0.0 info: title: Mon-entreprise API version: beta - description: Cet API expose les règles Publicodes de [mon-entreprise](https://mon-entreprise.urssaf.fr/). + description: | + Cet API expose les règles Publicodes de [mon-entreprise](https://mon-entreprise.urssaf.fr/). + + Pour plus d'informations, consultez [notre documentation](/d%C3%A9veloppeur/api). servers: - - url: https://mon-entreprise-api.osc-fr1.scalingo.io/api/v1/ + - url: /api/v1/ paths: {} diff --git a/api/source/test-e2e/__snapshots__/index.test.ts.snap b/api/source/test-e2e/__snapshots__/index.test.ts.snap index aed4e39ca..49b27bf60 100644 --- a/api/source/test-e2e/__snapshots__/index.test.ts.snap +++ b/api/source/test-e2e/__snapshots__/index.test.ts.snap @@ -924,7 +924,10 @@ exports[`e2e test mon-entreprise api > Test openapi.json endpoint 2`] = ` }, }, "info": { - "description": "Cet API expose les règles Publicodes de [mon-entreprise](https://mon-entreprise.urssaf.fr/).", + "description": "Cet API expose les règles Publicodes de [mon-entreprise](https://mon-entreprise.urssaf.fr/). + +Pour plus d'informations, consultez [notre documentation](/d%C3%A9veloppeur/api). +", "title": "Mon-entreprise API", "version": "beta", }, @@ -1064,7 +1067,7 @@ exports[`e2e test mon-entreprise api > Test openapi.json endpoint 2`] = ` }, "servers": [ { - "url": "https://mon-entreprise-api.osc-fr1.scalingo.io/api/v1/", + "url": "/api/v1/", }, ], } diff --git a/site/source/pages/integration/API.tsx b/site/source/pages/integration/API.tsx index c2cea6a94..167c38908 100644 --- a/site/source/pages/integration/API.tsx +++ b/site/source/pages/integration/API.tsx @@ -1,44 +1,15 @@ -import Emoji from '@/components/utils/Emoji' import { ScrollToTop } from '@/components/utils/Scroll' -import { H1, H2, H3 } from '@/design-system/typography/heading' +import { Message } from '@/design-system' +import { H1, H2, H3, H4 } from '@/design-system/typography/heading' import { Link } from '@/design-system/typography/link' import { Body } from '@/design-system/typography/paragraphs' import { Trans } from 'react-i18next' +import styled from 'styled-components' -const js = ` -async function salaireNetEnBrutMensuel(net) { - const body = { - situation: { - "contrat salarié . rémunération . net": net + " €", - }, - expressions: [ - "contrat salarié . rémunération . brut de base", - "contrat salarié . prix du travail", - ], - }; - - const response = await fetch( - "https://2138--mon-entreprise.netlify.app/api/v1/evaluate", - { - method: "post", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify(body), - } - ); - - console.log(response); - - const json = await response.json(); - - console.log(response.status); - console.log(json); - - return json.evaluate.map(({ nodeValue }) => nodeValue); -} - -const [brut, superBrut] = await salaireNetEnBrutMensuel(3500); - -console.log(brut, superBrut); +const InlineCode = styled.code` + background-color: #eee; + padding: 0.25rem; + border-radius: 0.25rem; ` export default function API() { @@ -48,29 +19,58 @@ export default function API() {

Utiliser notre API REST

- Si votre site ou service requiert de faire des calculs de salaire, par - exemple passer du salaire brut au salaire net, bonne nouvelle : tous - les calculs de cotisations et impôts qui sont derrière mon-entreprise - sont libres et utilisé via notre{' '} + Si votre site ou service requiert de faire des calculs sur des + salaires, par exemple passer du salaire brut au salaire net, bonne + nouvelle : tous les calculs de cotisations et impôts qui sont derrière + mon-entreprise sont libres et utilisable via notre{' '} API REST. - + {/* Google Sheets - + */}

Comment utiliser cette API ?

- Toutes nos règles de calculs sont écrites en `publicodes`, un language - déclaratif développé par beta.gouv.fr et l'Urssaf pour encoder des - algorithmes d'intérêt public.{' '} - En savoir plus sur publicodes + L'api mon-entreprise est totalement ouverte et sans authentification, + elle se compose de 3 routes qui s'inspirent des méthodes de + l'interpréteur Publicodes : /evaluate,{' '} + /rules et{' '} + /rules/:rule. - - {/*

Installation

*/} - 
-					{{ js }}
-
+ +

Qu'est ce que Publicodes ?

+ + C'est un language déclaratif développé par beta.gouv.fr et l'Urssaf + pour encoder des algorithmes d'intérêt public. +
+ Toutes nos règles de calculs sont donc écrites dans ce language. +
+ En savoir plus sur publicodes + + + +

POST /evaluate

+ + Permet d'évaluer les expressions de publicode avec une situation + donnée +
+ Vous trouverez plus d'infos sur la structure du JSON à envoyer sur + notre{' '} + Swagger. + + +

GET /rules

+ Permet de récupérer toutes les règles publicodes + +

GET /rules/:rule

+ Permet de récupérer une règle publicodes + +

Exemple

+ + Voici un exemple d'utilisation des différentes routes, vous pouvez + explorer leur code dans le dossier example +
- -

Lancer le calcul

- - Il ne vous reste plus qu'à paramétrer le moteur avec les règles du - paquet `modele-social` et à appeler la fonction `evaluate` sur la - règle que dont vous souhaitez la valeur. Voici un exemple pour le - calcul brut / net - -

Paramétrer le calcul

- - Vous l'aurez constaté dans l'exemple précédent, la recette d'un calcul - est simple : des variables d'entrée (le salaire brut), une ou - plusieurs variables de sorties (le salaire net). - - - Le calcul est cependant paramétrable avec toutes les possibilités - permise dans la legislation. - - - Toutes ces variables sont listées et expliquées sur la{' '} - - documentation en ligne - - . Cette documentation est auto-générée depuis les fichiers de règles - publicodes, elle est donc constamment à jour. - - - Lançons un calcul plus proche d'une fiche de paie : voici une - description de la situation d'entrée annotée de liens vers les pages - correspondantes de la documentation : - -
- - {' '} - Un{' '} - - cadre - {' '} - gagnant{' '} - - 3 400€ bruts - {' '} - , qui bénéficie de{' '} - - titres-restaurant - {' '} - et qui travaille dans une entreprise de{' '} - - 22 salariés - - . - -
)