- Moving forward, everything is done using Swagger. Ideally the code should contain the swagger, but until we're ready, keep the code/swagger decoupled.
- IRIS Maintains the RAML documentation, but we should re-evaluate if we ever do merge IRIS/Catapult
- Seems to have better tooling, and more traction in the open source community.
- Seems to have more industry backing / momentum.
- Swagger seems like the hip new thing with lots of traction
- At a first glance, Swagger seems to have a more active community, and more advanced support for technologies used by Catapult such as Spring MVC and JAX-RS.
- It has a broader community and it's more active.
- We've been using Swagger within our new project, and I've found it to be pretty decent in what it does. I will say I've never touched RAML, so my choice might be biased. The very few problems I have with swagger (ie. not being able to use OffsetDateTime for a date object) are very annoying. There are many things I like about swagger, one of the key thing is the ability to allow us to test calls through a fluid web UI.
- Billing/Backoffice already uses Swagger for documentation from code, works well, auto generated from code augmented by developer docs as you would expect. Built in online documentation and 'try it' tools, most important to us, it works for us in .NET and Java the same way with the same features. Is a collection of tools built against the OpenAPI spec, replacing some bits of it without replacing it all is part of the design. Certainly not married to Swagger, but see no compelling reason to change to something else.
- I like Iris' "live" documentation which I believe uses RAML, but some EVS microservices currently use swagger for internal documentation and (internal only) client SDK generation, so my vote is swagger to avoid redoc'ing those APIs in RAML.
- Swagger has stagnated, OAS is better integrated with AWS
- With RAML being separately maintained from the code, I find it's inaccurate more often than swagger stuff.
- Easier to keep docs and implementation in sync, more active development, better tools
- Because it generate docs automatically from code.
- Just because it's auto documentation
- Using Swagger properly requires you to design/architect APIs and their documentation up front and the auto-generation saves time writing interfaces that get a big repetitive manually. You can easily consume the yaml or interfaces it generates to make a client.
- Iris already has RAML and I'd like to keep the lowest common denominator
- Unless there is a problem with how Iris uses this, we should be consistent
- All Iris documentation is already in RAML; RAML allows to decouple API endpoint description and usage examples from Java code unlike Swagger; personally, I don't like when source code is bloated because of documentation inside; not only developers (product owner, product manager) can update RAML documentation.
- RAML is already familiar to all the team members including non-developers. We already have a substantial amount of documentation created in RAML and it has proved to be a pretty convenient technology. If we're consider changing to another tool, we'd need some time to at least get a minimal knowledge of it before making such a decision.
- Both have it pros and cons. raml Pros: We already use it. It doesn't force us to litter the code with meta data.
- Raml really suits Iris (I can't say about other projects). Yes, Swagger is more popular and progressive, but honestly I don't think that pros justify the means for rewriting API docs from raml to swagger.
- The only advantage I can see in Swagger is using annotations right in java code to make the docs but this solution is lack of functions we need like making examples. Keeping docs in JSON is less readable as in RAML.
- YAML - Easier for non-devs to read
- it seems for me that RAML is more customer oriented in sense that it is easier to understand it for people that are not familiar with code, it has more human readable format
- will be great to use one thing on both project
- Don't use it, or write it. I would be happy with either option, more importantly, that everyone can and will write and understand it.
- If there is a viable approach to represent XML and examples in swagger without manually converting payloads to JSON then it meets the needs, otherwise we need to stick with RAML.
- No matter what framework we use, it doesn't solve the main problem - outdated documentation.
- Not sure that it's reasonable today migrate to Swagger
- My team uses Swagger, but we are definitely interested in using the right tool that would be in line with the rest of the team. My vote leans towards swagger especially since it looks like other major companies are getting behind it pretty heavily.
- I don't think it matter between the two choice, both are very good from what I've read. I just want the team to pick one that everyone move forward with, acknowledging that each one will have it's own problems.
- Amazon votes for OAS too. AWS supports creating endpoints in API Gateway from OAS.
- One thing I would like is the ability to have internal and external documentation. Not sure if we can do this with swagger or not easily. We also sometimes want only portions of objects to be displayed in the documentation.