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

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

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)

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

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 Who’s using it in production? Full list: https://github.com/swagger-api/swagger-codegen/#companiesprojects-using-swagger-codegen

What are the lessons learned?

Lesson #1 - “Eat your own dog food” 8

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)

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

Lesson #2 - Test, Test, Test 11

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

Lesson #3 - Word of Mouth 13

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

Is your product gaining traction? 15

Lesson #4 Build a developer community 16

Have you heard of these terms? ▪ Microsoft MVP ▪ AWS Community Heroes ▪ Salesforce MVP ▪ Google Developers Experts 17

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

Lesson #5 Make it easy to contribute! 19

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

How the Rust client generator was created 21

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

Lesson #6 You can’t make everyone happy! 23

Remember WSDL? 24

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

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

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

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

THANKS! Any questions? Follow @oas_generator Star https://github.com/openapitools/openapi-generator (https://openapi-generator.tech) 29