Lessons Learned from Leading an Open-Source Project Supporting 30+ Programming Languages

Swagger Codegen, which is an open-source code generator for REST API, has become very popular in recent years. Many companies, from start-ups to IT conglomerates such as Cisco, IBM, VMWare, are using it in production to streamline the development process. The project covers a wide range of programming languages and server-side frameworks. How does the project grow from less than 50 contributors to 850+ contributors from all around the world with 10000+ commits in 4 years? William Cheng, the top contributor of Swagger Codegen, will share the journey the community went through and the lessons learned from building a vibrant developer community.

On May 2018, William Cheng and 40+ top contributors decided to fork Swagger Codegen to maintain a community-driven version called "OpenAPI Generator" (https://openapi-generator.tech). Please refer to the Q&A (http://bit.ly/2MS9w5h) for more information.

To learn more about OpenAPI Generator, the eBook "A Beginner's Guide to Code Generation for REST APIs (OpenAPI Generator)", available in 5 different languages: English, Française, 日本語, 简体中文, 繁体中文, is a good starting point: https://gumroad.com/wing328

Transcript

1. Lessons Learned from Leading an Open-Source Project Supporting 30+ Programming Languages William Cheng Core team & founding member of OpenAPI Generator https://openapi-generator.tech
2. William Cheng ▪ #1 contributor to Swagger Codegen ▪ Core team, founding member of OpenAPI Generator (https://openapi-generator.tech) ▪ eBook Author: https://gumroad.com/wing328 ▪ Founder of RESTUnited.com ▪ Morgan Stanley Alumni ▪ Github, Twitter: @wing328 2
3. What is Swagger Codegen? 3 [OUTPUT] API clients, server stubs, documentation • API clients (30 programming languages) • 30+ server frameworks • API Documentations • Apache2 web server config [INPUT] OpenAPI Spec For REST API • Swagger 1.2 • Swagger/OpenAPI 2.0 • Latest version OpenAPI 3.0.0 support is still work-in-progress [PROCESS] Swagger Codegen • Java package (JAR) • CLI • Brew (MacOS) • REST API • Docker • Plug-ins (Maven, Gradle, etc)
4. What an OpenAPI spec (v2.0) looks like? '/pet/{petId}': get: tags: - pet summary: Find pet by ID description: Returns a single pet operationId: getPetById produces: - application/json parameters: - name: petId in: path description: ID of pet to return required: true type: integer responses: '200': description: successful operation schema: $ref: '#/definitions/Pet' 4 Latest version (v3.0.1): https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md
5. A brief history of Swagger Codegen 5 Rewritten from Java to Scala 2012/ 2013 Rewritten in Java (again). Swagger acquired by SmartBear 2015 More stable releases with new generators 2016 10k commits, 800+ contributors, 7k ⭐ in Github. Tony Tam left SmartBear 2017 A community fork “OpenAPI Generator” by ~50 top contributors to support both OpenAPI v2, v3 (Ref: Q&A) 2018 May 2010 Swagger (UI, Editor, Codegen, Spec) created by Tony Tam and his team @ Wordnik/Reverb
6. 6 Who’s using it in production? Full list: https://github.com/swagger-api/swagger-codegen/#companiesprojects-using-swagger-codegen
7. What are the lessons learned?
8. Lesson #1 - “Eat your own dog food” 8
9. 9 Eat your own dog food is a colloquialism that describes a company using its own products or services for its internal operations. (The term is believed to have originated with Microsoft in the 1980s. Ref: https://www.investopedia.com/terms/e/eatyourowndogfood.asp#ix zz5JKqZMV63)
10. REST API Backend Migration Swagger Codegen (2.4.0) => OpenAPI Generator (3.0.0) - Issue with web service’s dependency (conflicted with new parser that supports OpenAPI spec v3.0) Solution: Migrate REST API backend from JAX-RS to Spring Boot 1. Locate the OpenAPI spec 2.0 describing the REST API 2. Generate Spring Boot server stub using OpenAPI Generator 3. “Copy & paste” application logic 4. Generated, migrated, tested and deployed within 24 hours 10
11. Lesson #2 - Test, Test, Test 11
12. Common mistakes found in other projects - Don’t test - Skip/Remove tests - Assuming users will always report the issue - Ignore your product without reporting issues - Bad mouth your product - Poor documentation - Incorrect instructions - Too difficult to follow - Outdated - 12
13. Lesson #3 - Word of Mouth 13
14. Marketing your product/project • $0 marketing budget • No Ads • No sponsorship • “word of mouth” by the community ◦ Presentations, blog posts (Chinese, English, French, Japanese, etc) ◦ Youtube tutorials • Growth hacking ◦ “Generated by OpenAPI Generator …” ◦ .openapi-generator-ignore file ◦ Script for publishing the code to Github 14
15. Is your product gaining traction? 15
16. Lesson #4 Build a developer community 16
17. Have you heard of these terms? ▪ Microsoft MVP ▪ AWS Community Heroes ▪ Salesforce MVP ▪ Google Developers Experts 17
18. How we segment the community? 18 1 Core team members Spend at less 3 hours per week for at least 3 months on the project 3 Template Creators Submit a new generator for a new language or framework 5 Users These users may have reported an issue, asked questions or provided feedback to the project. 2 Technical committees At least 3 merged pull requests for a particular generator or programing language 4 Contributors File a PR to fix bugs, enhance the generators or improve the documentation
19. Lesson #5 Make it easy to contribute! 19
20. Show them the way Me: Can you please submit a PR with the suggested enhancement? User 1: I don’t know git … Me: Here are the step by step instructions (documented in the FAQ) User 2: This line in the Ruby client is causing issues Me: Here is the line in the mustache template file to fix the issue 20
21. How the Rust client generator was created 21
22. High-level overview of the process 22 Lorem 3 • Perform integration tests and refine the work-in-progress Rust client generator • Release a beta version of the generator to collect more feedback Lorem 1 • Create Rust Petstore client • Implement 2 endpoints only ◦ getPetById (HTTP GET) ◦ addPet(HTTP POST) • Test to ensure it works with Petstore server Lorem 2 Based on the functional Rust Petstore client, “reverse engineering” the Rust generator (Java), mustache templates for API, models and other files. Test and Refine Creation of Rust Petstore client Reverse Engineering
23. Lesson #6 You can’t make everyone happy! 23
24. Remember WSDL? 24
25. About OpenAPI Generator - a community driven version of Swagger Codegen 1. Founded by about 50 top contributors of Swagger Codegen 2. A fork of Swagger Codegen 2.4.0-SNAPSHOT 3. OpenAPITools.org (parent organization of OpenAPI Generator) is not affiliated with OpenAPI Initiatives (OAI) https://openapi-generator.tech 25
26. Why forked the project? Top 3 reasons 1. Most test cases in the generators were commented out in Swagger Codegen 3.0.0 (beta) 2. Swagger Codegen 3.0.0 (beta) contains too many breaking changes 3. Changes made directly to 3.0.0 branch without reviews or tests were breaking the builds from time to time (e.g. “mvn clean package” failed) More reasons in the Q&A https://github.com/OpenAPITools/openapi-generator/blob/master/docs/qna.md#why-was -it-decided-to-fork-swagger-codegen-and-to-maintain-a-community-driven-version 26
27. Why choose OpenAPI Generator? ▪ Supports both OpenAPI Spec v2, v3 ▪ Easy migration path from earlier versions ▪ More rapid release cycle (weekly for patch release) ▪ More new generators 27
28. Credits ▪ 900+ contributors to the project ▪ Presentation template by SlidesCarnival ▪ Photo credits ▫ https://pixnio.com/fauna-animals/dogs/puppy-dog-pet-animal-bone-food ▫ https://en.wikipedia.org/wiki/History_of_Microsoft ▫ https://pixabay.com/zh/%E8%B7%AF%E6%A0%87-%E6%AD%A3%E7%A1%AE%E7%9A%84%E 6%96%B9%E6%B3%95-%E6%B5%8B%E8%AF%95-%E8%83%BD%E5%8A%9B%E5%80%BE%E5 %90%91%E6%B5%8B%E9%AA%8C-%E5%AE%9E%E9%AA%8C-%E6%8E%A7%E5%88%B6-%E7 %A4%BA%E4%BE%8B-%E8%B0%83%E6%9F%A5-361513/ ▫ https://pixabay.com/zh/%E9%BA%BB%E9%9B%80-%E9%BA%BB%E9%9B%80%E7%9A%84% E5%AE%B6%E5%BA%AD-%E9%B8%9F%E7%B1%BB-%E8%81%8A%E5%A4%A9-%E7%BB%84- %E4%B8%80%E8%B5%B7-%E5%9C%A8%E4%B8%80%E8%B5%B7-%E5%9B%A2%E9%98%9F- %E9%9B%86%E4%BD%93-2759978/ ▫ https://giphy.com/gifs/michael-strahan-enTimXqzmVXR6 ▫ https://www.flickr.com/photos/dumfstar/8553473662 28
29. THANKS! Any questions? Follow @oas_generator Star https://github.com/openapitools/openapi-generator (https://openapi-generator.tech) 29