Swift Class Diagrams and more

martinmitrevski

Introduction

Documentation is one of the things that developers don’t like to do much – but it’s something very important not only for newcomers to the project, but also to the people who originaly have written that code. We tend to forget what’ve done two weeks ago, so it’s always good idea to write down what we were trying to achieve with that code. Apart from the docs, it’s very useful to have a drawing which will provide a high level overview of the architecture of the app we are doing – what classes, value types and protocols we are using, how are they connected to each other and what methods and properties they have. Something like a UML class diagram of the current state of the project.

Note: We have a new tool now, have a look at it here.

For other languages there are several great tools available, but with Swift being a young language, there is still a room for improvement. There are tools that can create graphs out of the code, like this Objc Dependency Visualiser and this Swift Relationship Graph, but they are not generating class diagrams. One person who is tackling this is my buddy Jovan Jovanovski, with the help of another one of my buddies, Zdravko Nikolovski.

How does it look like?

They are doing an open source library (https://github.com/yoshimkd/swift-auto-diagram), which provides fast and easy generation of an html page with class diagrams of the current state of the project. How to use it? These are the three steps:

1. Clone the git repo:

git clone https://github.com/yoshimkd/swift-auto-diagram

2. Run the generateClassDiagram.rb script with the path of your project as an argument:

ruby generateEntityDiagram.rb ~/workspace/my-swift-project

3. Open the generated html and enjoy the diagrams of your classes, structures and protocols.

screen-shot-2016-10-09-at-10-32-43

After the html is generated, you can drag and re-order the drawn classes in any way you want. All of the different types (classes, structs, protocols, extensions) are in different colors, making it easier to distinguish them.

This script is implemented by string manipulations – all of the types with their properties are extracted from the Swift files and send out to a drawing library which creates the needed html.

If you don’t specify any command line arguments then the script will search for all swift files in the script’s main directory. You can specify any number of command line arguments which should be existing directory or file paths. The directories will be searched in depth for swift files recursively.

Good thing about this being a ruby script is that you can add it as a run script phase to your project’s Build Phases. The script will update the html of the class diagram any time you build the project, therefore always providing an up-to date overview of the state of your project.

Screen Shot 2017-10-03 at 22.31.55

Conclusion

This simple tool might be handy to any Swift developer – it provides a visual overview of the current state of your project. It’s also useful for explaining the architecture of the app to newcomers in the team. Still, there’s a room for improvement of this tool and the creators of it would be more than happy to accept your pull requests and bug reports. For example, one thing that needs to be improved is opening the html diagram in Safari – currently it works best on Google Chrome.

38 Comments

  2. How long did is take to scan the project ?
    How can I see scanning progress?
    —-
    I have been waiting for 10 minutes and see only gray circle.

    Like

    Reply
  4. Pingback: A year of tech blogging – martinmitrevski

  8. Hey Martin, it seems like a much of work your bodies done, thank for it. But I’m relative new in mac “world” and I have some problems to make it run. I have already run the command “git clone….” in terminal, also download the project from GitHub. And now if I input the general command “ruby generateEntityDiagram.rb”
    I get the message: “ruby: No such file or directory — generateEntityDiagram.rb (LoadError)
    Ruby is already installed with homebrew. Have you maybe some ideas to my issue.
    Thank in advance.

    Like

    Reply

    1. Hi there. It seems you are not in the right directory. You should go to the directory where you have cloned the swift class diagram tool and run the script from there. Also, be careful to provide the right path to the iOS project, as described in the sample above. Hope that helps.

      Like

      Reply

  9. Martin thank you for so much fast answer, so the complete command would look like:
    ruby generateEntityDiagram.rb~/user/directory/..(is the syntax with the tilde right), sorry for so much dumb answers:)

    Like

    Reply

  10. Diagram got generated for my project in html file. But it takes too long time(more than 10 minutes) to load the file. Is there any option where I can get PNG format diagram?

    Like

    Reply

    1. Currently there’s no option to get a PNG directly from the tool. Only option is to take screenshot of the browser if the diagram fits the whole screen. You can suggest the PNG feature on the GitHub repo.

      Like

      Reply

  11. Thank you for your reply. I tried to take screenshot but my diagram does not fit in the screen and one more question since my diagram is clumsy I just dragged the components. But the position after dragging is not getting saved. Each time I open html I need to wait for 10 minutes and it loads original image.

    Like

    Reply

    1. Persisting the positions of the components is currently not implemented, although the creators have plan to enable that in the future. About the load time, that’s strange, usually it’s few seconds. Which browser are you using?

      Like

      Reply

  13. When I tried open this in firefox I am getting message saying diagam.js is busy or may stopped responding.and it will take time to execute. Because of this loading time I will not be able to go with this approach. Will you be able to help me?

    Like

    Reply
  15. Pingback: generate Class diagram for iphone app - QuestionFocus

  16. Nice tool for swift class diagram. I found on issue that its only show protocol conformance and inheritance relation. It’s not showing relation for instance variable.(has-a relation). Is there any way to configure this while running script.
    Thanks

    Like

    Reply

  17. I input the general command “ruby generateEntityDiagram.rb”
    run code : “ruby generateEntityDiagram.rb /Users/ios_developer/Projects/IOS”
    this directory is true
    but return error
    I get the message: “ruby: No such file or directory — generateEntityDiagram.rb (LoadError)
    Thank in advance.

    Like

    Reply

    1. You need to run the script generateEntityDiagram.rb from the location where you have cloned/downloaded the tool. Other option is to specify the full path to the script and run it from anywhere, for example: “ruby /Users/ios_developer/Projects/SwiftDiagram/generateEntityDiagram.rb /Users/ios_developer/Projects/IOS”

      Like

      Reply
  18. Pingback: Swift code types navigator – martinmitrevski

  22. Hi.
    I just tried this tool and instead of classes with methods and properties I only get ellipses that show class names.
    If you knew how could I get properties and methods it would help a lot.

    Like

    Reply
  23. Pingback: Swift Class Diagrams Remastered – martinmitrevski
  25. Pingback: UML class diagrams for Xcode (swift programming) - iZZiSwift

Leave a comment