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