Swift Class Diagrams and more

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.

Advertisements

32 thoughts on “Swift Class Diagrams and more

  1. 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

  2. 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

    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

  3. 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

    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

  4. 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

    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

  5. 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

  6. 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

  7. 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

    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

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

w

Connecting to %s