Hi Everyone, What I'm trying to do primarily is setting up Swagger-based docs for EMM/IoTS related APIs. However, while I was looking deeper into this, came across a few things that I need clarifications upon.
*Code-first or Contract-first?* Right now it appears that there are two approaches being used in the platform for API design and development. 1. Contract first approach, which utilizes composing the Swagger definition upfront and then generating the API implementation out of it. (** I do understand that there's a whole big debate around different developer communities as to whether REST needs a contract, except for the HTTP protocol, at all. But, the primary intention of this thread is "not" to jump into a similar argument :) ) 2. Code first approach, which utilizes implementing the API first and then generates Swagger definition to be used for documentation purposes, etc. Each approach obviously has its own pros and cons. This is, therefore, to see what needs to be/already have standardized as the best approach to go about API design and implementation. If we consider contract-first approach, that looks more elegant and lets us enable enforcing proper governance across the API design and implementation process. For instance, folks can first work on the Swagger definition as the contract, at the design phase and then go into the implementations later on after verifying the resource definitions, etc. The second approach, on the other hand, makes it easier for us to deal with in terms of implementing complex and more coarse-grained HTTP APIs (which I believe is a common-case in the platform?) and exposing their definitions. *Impact of this on API documentation* So, coming back to the topic of documenting APIs with what was discussed earlier, if we go by the first approach, there we have the swagger definition up-front so we wouldn't need to go for any annotation-based models, etc and instead, can directly generate API documentation based on the existing Swagger definition via an appropriate doc generator tool. In contrast, the code-first approach demands us to go for an annotation-model or something similar to get the documentation done. Whichever the case would ultimately produce the same output, but I thought, as a platform we need to stick to just one approach and document it properly. So the question is, what would that be? Cheers, Prabath -- Prabath Abeysekara Technical Lead WSO2 Inc. Email: [email protected] Mobile: +94774171471
_______________________________________________ Architecture mailing list [email protected] https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
