API Design & Documentation Using Open Source Tools

[API Dev]

We plan to use Open API 3 specification for designing API's that are required to build our enterprise web application. These API's are being developed to integrate the backend with frontend. They are initially planned to be internal/private. To roll out an API First strategy across multiple teams (~ 30) in our organization we want to recommend and centrally deploy a standard set of tools that could be used by teams to design and document API's. 

I am new to the swagger tool set. I understand that there is a swagger-editor tool that can help in API design while swagger-ui could help in API documentation. Trying them I realized a few problems

1. How would teams save their API's centrally on a server? Swagger editor does not provide a way to centrally store them. 

2. How can we get a directory look up that displays all the designed API's?

3. How can we integrate the API design and API documentation tool?

4. How can the API specifications be linked with the implementation (java) to keep them up-to-date?

5. How do we show API dependencies when one api uses the other one?

We basically need to think about the end-to-end work-flow that helps teams in their SDLC to design API's. For the start I am trying to see what can we achieve with free tools. 

Can someone share their thoughts based on their experience?

Thanks!

[Henry Andrews (JSON Schema)]

There are some good articles on various aspects of this at https://blog.apisyouwonthate.com/

There's a related slack channel as well

cheers,

-henry