Post on 03-Dec-2018
Swagger2estmort,viveOpenAPI3Speakers:SébastienLecacheur,GrégoryBloquelFormat:ConférenceDate:20avril2018Laquestiondeladocumentationd’uneAPIestimportante.Lorsdesamiseenplace,lesspeakersavaientpourexigences:
• Documentationpourlesutilisateursinternesouexternes.• Approchecontract-first:rédigerladocavantd’écrirelecode• Documentationgéréecommelecode• Documentationlisibleparleshumains
Wordneconvenaitpas.IlsontoptépourSwagger.ConcurrentsdeSwagger:RAMLetBlueprintSwaggerHistoriquedeSwagger:
• Swagger1estsortien2010.• En2014estsortilaV2.• En2015:démarragedel’OpenAPIInitativeauseindelafondationLinuxàpartirde
Swagger2.• En2017,Swagger3estsortietutilisel’OAI.Swagger3estuneimplémentationde
l’API.OpenAPIInitiativeréunitdenombreuxacteurs:WSO2,Mulesoft,Microsoft,….Touslesacteursindustrielsmajeurssesontmisd’accord.Swaggeraétépopulariséen2014parsonapprochecodefirst.Documentationgénéréeàpartirdesannotationsetdoncducode.Présentationdel’approcheContractFirstOncommencepardesURIetdesexemples.Cycleitératifaveclemétieretlesutilisateurspourarriveràuncontratd’interfacestable.Outrelagénérationdedocumentation,onpeutajouterdelagénérationdetests,decode,democks.RappelsurlesAPIsREST:
• URIcommeidentifiantderessource• Verbecommeidentifiantd’opération• RéponseHTTPcommereprésentationdelaressource(enJSONparexemple)• Lienscommerelationentrelesressources(HATEOS)
NouveautésdeOAS3.0.1
• Deloin,pasdegroschangements• OutilOpenAPIMappournaviguerdansladocumentation• Editeurenligneeditor.swagger.ioououtilSwaggereditor
NouveautésdeSwagger3
• DescriptionmigréedeGFMversCommonMark• GestiondesversionsenSemanticVersionning:versionsur3digitsx.y.e• MontéedeversionàJSONSchemaWrightDraft00
o Nouveauxtypessupprotés:oneOf…La1ièreligned’unfichierYAMLdeSwaggerpréciselaversionSwagger:"2.0"Openapi:"3.0.1"Nouveautésserveur:
• URLpermettantdepréciserdifférentsserveurs(production,staging)• Varialibilsationdel’URL,parexempleaveclenomdel’environnement• Possibilitédesurchargerleserverdanschaqueendpoint
Nouveautéssécurité:
• Basicdevienthttp• SupportdeOpenIDConnect• OAuth2updated• Ajoutde«Scheme»et«bearerformat»
Nouveautéscomposants:
• UncomposantpeutêtreréutilisédansladéfinitiondesAPI• Beaucoupdedéplacement/renommage
Nouveautéssurleformatdesrequêtes:
• Wildcardspourlescodesderetour(ex:5XX):onn’exposepaslecodedeserreursserveursinternesauconsommateur
• oneOf/anyOfpourduPolymorphsime/CompositionNouveautéssurlescallbacks:
• Supportdeswebhooko Permetdenotifierunutilisateurdel’APIentempsréeld’unévénement
• Onpeutajouterdesexemples
NouveautéLink:
• Définirunerelationentreuneréponseetd’autresopérationso Opérationspossibleso Pagination(cursor):identifiantdecurseurréutilisablepourappelsuivant
Outils:
• Editeurswagger-editor• Générationdecode:swagger-codegen
o Générateurderéférence.RéécritenSwagger3.o Swagger-code-generatorso Client/serverJava,JAXS,Kotlin,HTMLo Changementdumoteurdetemplating:mustache=>handlebaro PullRequestpourPHPetScala
• LesautresgénérateursditscompatiblesOpenAPI3fonctionnentmoinsbien.Bienveilleràlesqualifier.
Futurd’OpenAPI:
• Issues1466• Limitations
o Pasdetraits:décrireuncomportement(filtrable,cachable…)o Pasderesourcestypes:déclarationdetypederessourcesafindemutualiser
ducomportemententreressources(avecsurchargepossible)o Pasdetemplatingdescomposants:surlaréponsed’unPOST,onnepeutpas
mettre‘montalkaétégénéré’mais‘maressourceaétégénérée’=>ondoitrestergénérique