{"id":15964715,"url":"https://github.com/tomi-vanek/microts","last_synced_at":"2025-03-16T07:31:50.382Z","repository":{"id":33990216,"uuid":"165400292","full_name":"tomi-vanek/microts","owner":"tomi-vanek","description":"Microservice code generator: from OpenAPI (Swagger) REST API specification to TypeScript project with Docker.","archived":false,"fork":false,"pushed_at":"2024-05-02T01:05:14.000Z","size":236,"stargazers_count":29,"open_issues_count":4,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-07T06:33:24.628Z","etag":null,"topics":["code-generator","docker","docker-compose","microservice","openapi","swagger","typescript"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tomi-vanek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-12T15:00:44.000Z","updated_at":"2024-06-04T23:53:24.000Z","dependencies_parsed_at":"2024-05-02T02:28:52.865Z","dependency_job_id":"7990dcdf-412e-400c-9fde-d2e32bad174d","html_url":"https://github.com/tomi-vanek/microts","commit_stats":{"total_commits":37,"total_committers":3,"mean_commits":"12.333333333333334","dds":0.3513513513513513,"last_synced_commit":"98d3d4cdc08724d665e5f7b2019de1bd2b7001de"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomi-vanek%2Fmicrots","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomi-vanek%2Fmicrots/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomi-vanek%2Fmicrots/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomi-vanek%2Fmicrots/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomi-vanek","download_url":"https://codeload.github.com/tomi-vanek/microts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243806035,"owners_count":20350775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-generator","docker","docker-compose","microservice","openapi","swagger","typescript"],"created_at":"2024-10-07T17:04:06.098Z","updated_at":"2025-03-16T07:31:49.961Z","avatar_url":"https://github.com/tomi-vanek.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MicroTS code generator for microservices\n\nMicroservice code generator with interface-first approach: from **OpenAPI - Swagger** REST API specification is generated complete project skeleton with _TypeScript_ code, tests and _Docker_ configuration.\n\nGenerated code has the ambition to minimize implementation time for new microservices.\n\nThe _openapi-micro-ts_ generator is a simple \"one-shot\" project initialization tool - after the code is generated, the service functionality is implemented with traditional manual coding.\n\n## Quick start\n\n1. Install the generator with `npm i -g microts`\n1. Create a new project directory. Go to the new project work directory with `cd [NEW-PROJECT]`.\n1. Create new microservice schema with default name `swagger.yaml` in root of the project.\n1. Generate microservice code with command `microts` with default port 3000.\n1. Nstall dependencies with `npm i` and start the microservice with `npm start`.\n1. Open the microservice debugging user interface in browser with URL `localhost:3000/[base-path]/ui` (base path is defined by schema).\n\n## Code generation in detail\n\n1. Create a new project directory (create a project in GitHub or other VCS and clone). Go to the new project work directory with `cd [NEW-PROJECT]`.\n1. Create new microservice schema in root of the project. Supproted schema formats are [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) in both YAML and JSON format.\n1. Generate microservice code with command `microts -p PORT -s SCHEMA`. Parameter PORT defines the default port on which the server will listen (if not set, default port 3000 will be used for code generation). Parameter SCHEMA is the name of the schema - may be with absolute or relative path, if schema is not in working directory. If schema is not set, generator tries to open `swagger.yaml` file for API definition.\n1. Read the _Next steps_ in the console and familiarize with the generated microservice server.\n1. More information about the microservice is in the generated `README.md` file.\n1. Add repository and license fields to the generated `package.json`.\n1. The source schema was copied (and if needed - converted) to `src/conf/swagger.yaml` file. The source schema can be deleted - as it is not used by the server.\n1. Search for `TODO` in code, and implement the functionality.\n\nFor all command line properties of the `microts` code generator use the command `microts -h`.\n\n## Microservice development\n\n1. For debugging run the microservice with `npm run dev`.\n1. After saving any change the source code is compiled to runtime form in `/dist` directory and the server is restarted.\n1. The microservice UI helps by debugging the service. It shows also `curl` commands to call the actions in the service.\n\n## OpenAPI / Swagger schema authoring\n\nMicroservice is declared with OpenAPI 2.0 (Swagger) `swagger.yaml` schema with API definition - you can use Swgger editor for schema definition. This design step is crucial for further quality and usage simplicity of the new API. Design is best made in discussion. It may be useful to author the schema with [Online Swagger Editor](https://editor.swagger.io/).\n\nFor cloud deployments code generator generates code for health check, if in schema is defined action `GET /health`.\n\n## Generator code from GitHub\n\n1. Download the generator with `git clone https://github.com/tomi-vanek/openapi-micro-ts.git` and go to project repository with `cd microts`\n1. Download generator dependencies and tools with `npm i`.\n1. Register the tool in local NPM with `npm link` command, so you can use it from command line in any directory with command `microts`.\n\n## Generator in detail\n\nThe microservice interface is defined in form of [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) schema, as the libraries / tools used in generated code do not support the current version of OpenAPI yet.\n\nGenerated application code is in TypeScript language.\n\nBasic features of the generated code:\n\n* TypeScript language\n* Application configuration in directory `/src/conf`\n* Node \u0026 Express server setup in `/src`\n* Convention-based routing and request handlers in `/src/handlers` - request path corresponds the directory path, no explicit routing logic is needed\n* Zero-code automatic input validation defined by rules in OpenAPI / Swagger schema\n* User interface for microservice testing and administration in `/src/ui`\n* `Dockerfile` for deployment image and `docker-compose.yaml` as an example usage in application integration\n* End-to-end tests  in `/test`\n\n## Architecture shape\n\nGenerator does not offer rich set of options to tailor the result into different forms. This approach expresses author's architecture experience: generator is a way to define architecture without complex documentation, that gently directs developers in the architecture-envisioned direction:\n\n* Developers are implementing the application logic in request handlers and tests.\n* Non-functional concerns are hidden in the generated code.\n* Implementation of microservice \"from zero\" is very fast - removes time \u0026 effort concerns by introducing new or radical refactoring of existing services in system ecosystem.\n\nGenerator in architecture:\n\n* Operational definition of the architecture (as a replacement of write-only obsolete documentation :-)\n* Consistency of project structure - simple global refactoring by changes of the runtime environment\n* Developer focus on application code (minimizes developer's creativity in non-functional runtime and security concerns)\n\nAs an architect you have your own technical opinion, technology constraints / preferences and infrastructure \u0026 security services that have to be integrated into the (micro)service servers.\n\nJust fork this project, or take an inspiration and build your own generator from an proof-of-concept service that best fits your expectations.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomi-vanek%2Fmicrots","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomi-vanek%2Fmicrots","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomi-vanek%2Fmicrots/lists"}