{"id":859,"date":"2021-01-10T19:35:00","date_gmt":"2021-01-10T18:35:00","guid":{"rendered":"https:\/\/racs.es\/?p=859"},"modified":"2021-01-11T18:20:53","modified_gmt":"2021-01-11T17:20:53","slug":"generate-your-api-code-from-openapi-swagger-without-effort","status":"publish","type":"post","link":"https:\/\/racs.es\/en\/generate-your-api-code-from-openapi-swagger-without-effort\/","title":{"rendered":"Generate your API code from OpenAPI\/Swagger without\u00a0effort!"},"content":{"rendered":"\n<h6 class=\"wp-block-heading\">Boost your development and save a lot of&nbsp;time<\/h6>\n\n\n\n<hr class=\"wp-block-separator\"\/>\n\n\n\n<h3 class=\"wp-block-heading\">Introduction<\/h3>\n\n\n\n<p>How many times did you have to create manually all models and API calls for the app or external service that you were working on? And even worst\u2026 When they have some OpenAPI standard!<\/p>\n\n\n\n<p>Yes, I know, even Swagger provides you an application that generates this code, but at the moment I tried it, the result code was messy and hard to configure (also heavy), and for the current time, there are more applications that provides you a lot of code, but I want to get my own by myself with <strong>native support for JavaScript<\/strong>.<\/p>\n\n\n\n<p>So around two years ago I wrote my first approach to solve this for myself, that code was too bad, so I never publish it, but some weeks ago I need the solution again for Open API V3. So\u2026 I had to write it again from scratch, but this time with a bit more planning.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">About the&nbsp;project<\/h3>\n\n\n\n<blockquote class=\"wp-block-quote\"><p>The project is Open Source, you can star or fork it on GitHub: <a href=\"https:\/\/github.com\/ProtocolNebula\/ts-openapi-generator\" rel=\"noreferrer noopener\" target=\"_blank\">https:\/\/github.com\/ProtocolNebula\/ts-openapi-generator<\/a>.<\/p><\/blockquote>\n\n\n\n<p>Is written in <strong>TypeScript<\/strong> but is only to generate the files, so don\u2019t worry, it will be useful <strong>even<\/strong> for your <strong>assembly<\/strong> application&nbsp;;).<\/p>\n\n\n\n<p>At this moment it only comes with an Angular 2 template, but <strong>you can create your own<\/strong> or <strong>wait until more are added.<\/strong><\/p>\n\n\n\n<blockquote class=\"wp-block-quote\"><p>You can push templates and contribute to the project&nbsp;:).<\/p><\/blockquote>\n\n\n\n<h4 class=\"wp-block-heading\">Supported documents<\/h4>\n\n\n\n<p>It currently supports <strong>Swagger 1<\/strong>, <strong>Swagger 2<\/strong> (OpenAPI), and <strong>OpenAPI V3<\/strong>.<\/p>\n\n\n\n<blockquote class=\"wp-block-quote\"><p>The script use <strong>converters <\/strong>(<a href=\"https:\/\/github.com\/LucyBot-Inc\/api-spec-converter\" rel=\"noreferrer noopener\" target=\"_blank\">api-spec-converter<\/a>) to OpenAPI V3 which are automatically applied to the file.<\/p><\/blockquote>\n\n\n\n<p>Is planned to support more standard documents.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\">OpenAPI V3 specs&nbsp;support<\/h4>\n\n\n\n<p>At this moment <strong>not all specs<\/strong> are supported, there are some a bit hard to implement in some languages, like <strong>OneOf<\/strong> or <strong>AnyOf<\/strong>, there are planned solutions but will take some days to check that those methods are easy to customize.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Installation and&nbsp;use<\/h3>\n\n\n\n<h4 class=\"wp-block-heading\">Install globally<\/h4>\n\n\n\n<p>If you wanna use this at \u201cfreestyle\u201d (normal CLI) you have to install it globally:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"bash\" class=\"language-bash\"><code>npm i -g @protocolnebula\/ts-openapi-generator<\/code><\/code><\/pre>\n\n\n\n<h4 class=\"wp-block-heading\">Install locally<\/h4>\n\n\n\n<p>On the other hand, if you prefer to automatize this process into a project, you have to install it locally:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"bash\" class=\"language-bash\">npm i @protocolnebula\/ts-openapi-generator<\/code><\/pre>\n\n\n\n<h4 class=\"wp-block-heading\">How to&nbsp;use<\/h4>\n\n\n\n<p>There are some ways to initialize, the most common is to launch the script (pending command name revision), for example, if you launch:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"bash\" class=\"language-bash\">transform-swagger -f <a href=\"https:\/\/raw.githubusercontent.com\/ProtocolNebula\/ts-openapi-generator\/main\/examples\/openApiFiles\/passportescaperoom.com.json\" rel=\"noreferrer noopener\" target=\"_blank\">https:\/\/raw.githubusercontent.com\/ProtocolNebula\/ts-openapi-generator\/main\/examples\/openApiFiles\/passportescaperoom.com.json<\/a> -o src\/generatedApi\/ -t angular2<\/code><\/pre>\n\n\n\n<p>You can find a new folder structure: <strong>src\/generatedApi<\/strong> with the generated files.<\/p>\n\n\n\n<blockquote class=\"wp-block-quote\"><p>You can check the <a href=\"https:\/\/github.com\/ProtocolNebula\/ts-openapi-generator\/tree\/main\/examples\" rel=\"noreferrer noopener\" target=\"_blank\">examples in the GitHub<\/a>&nbsp;project.<\/p><\/blockquote>\n\n\n\n<p>This script will do:<\/p>\n\n\n\n<ul><li><strong>-f<\/strong>: Specify which file will be parsed or <strong>downloaded<\/strong> (you can specify some local file).<\/li><li><strong>-o:<\/strong> output folder in which the data will be generated (the folder will be cleared after each execution).<\/li><li><strong>-t:<\/strong> Template to use, in this case, <strong>angular2<\/strong>, you can create your template and set it as a <strong>relative path<\/strong>. (EX:&nbsp;.\/templates\/myPHPTemplate)<\/li><\/ul>\n\n\n\n<p>Alternatively you can create a <strong>json<\/strong> config file with this settings:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"json\" class=\"language-json\">{\n  \"file\": \"<a rel=\"noreferrer noopener\" href=\"https:\/\/raw.githubusercontent.com\/ProtocolNebula\/ts-openapi-generator\/main\/examples\/openApiFiles\/passportescaperoom.com.json\" target=\"_blank\">https:\/\/raw.githubusercontent.com\/ProtocolNebula\/ts-openapi-generator\/main\/examples\/openApiFiles\/passportescaperoom.com.json<\/a>\",\n  \"outputFolder\": \"src\/generatedApi\/\",\n  \"template\": \"angular2\",\n  \"saveFile\": \"tempOpenApiFile\"\n}<\/code><\/pre>\n\n\n\n<p>And launch the script with the command:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"bash\" class=\"language-bash\">transform-swagger --config-file <strong>yourSettings.json<\/strong><\/code><\/pre>\n\n\n\n<h4 class=\"wp-block-heading\">Using the generated files<\/h4>\n\n\n\n<blockquote class=\"wp-block-quote\"><p>The <strong>angular2 <\/strong>template has a dependency (as you can see in the generated files) which is \u201cApiBase\u201d, this is <strong>my custom<\/strong> layer for <strong>service requests<\/strong> in my angular project, but you can create your one (just change the templates).<\/p><\/blockquote>\n\n\n\n<p>If want to use the current <strong>Angular 2 template<\/strong>, just copy <strong>ApiBase<\/strong> folder to your project at the <strong>same parent<\/strong> as the generated files (you can manually download from GitHub instead):<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"bash\" class=\"language-bash\">cp -r <strong>node_modules\/ts-openapi-generator\/ApiBase<\/strong> src\/ApiBase<\/code><\/pre>\n\n\n\n<blockquote class=\"wp-block-quote\"><p>At this point, you can <strong>use <\/strong>the generated API files in your project using normal imports, that\u2019s all (check that are provided as&nbsp;root).<\/p><\/blockquote>\n\n\n\n<h3 class=\"wp-block-heading\">Custom templates<\/h3>\n\n\n\n<p><em>Please, note that because this project is in an earlier phase, some changes can be done to the templating system.<\/em><\/p>\n\n\n\n<p>As described in the <a href=\"https:\/\/github.com\/ProtocolNebula\/ts-openapi-generator\/tree\/main\/templates\" rel=\"noreferrer noopener\" target=\"_blank\">template tutorial,<\/a> you can do a custom template, summarizing:<\/p>\n\n\n\n<ol><li>Copy and paste <strong>templates\/angular2<\/strong> folder to your desired folder (or into <strong>templates\/<\/strong> if you wanna push to the main repo).<\/li><li>Modify the files inside the folder.<\/li><li>Generate with your templates! (<strong>-t<\/strong> option)<\/li><\/ol>\n\n\n\n<hr class=\"wp-block-separator\"\/>\n\n\n\n<p>At this point, you should create and use your custom APIs and Models consumed from any OpenAPI file.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Contribute to the&nbsp;project<\/h3>\n\n\n\n<p>Don\u2019t forget that this is an <strong>Open Source<\/strong> project, so you can contribute in many ways, for example, <strong>Starring<\/strong> the project or <strong>Pushing<\/strong> code (doing a fork).<\/p>\n\n\n\n<p>You can also contribute with money to the project or other projects I want to make (just check the <strong>contribute<\/strong> option in GitHub).<\/p>\n\n\n\n<p>I hope this will be useful to you!<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Boost your development and save a lot of&nbsp;time Introduction How many times did you have to create manually all models and API calls for the app or external service that you were working on? And even worst\u2026 When they have some OpenAPI standard! Yes, I know, even Swagger provides you an application that generates this [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":862,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"_exactmetrics_skip_tracking":false,"_exactmetrics_sitenote_active":false,"_exactmetrics_sitenote_note":"","_exactmetrics_sitenote_category":0,"footnotes":""},"categories":[237],"tags":[249,250,244,248,246,243,242,247],"acf":[],"_links":{"self":[{"href":"https:\/\/racs.es\/en\/wp-json\/wp\/v2\/posts\/859"}],"collection":[{"href":"https:\/\/racs.es\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/racs.es\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/racs.es\/en\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/racs.es\/en\/wp-json\/wp\/v2\/comments?post=859"}],"version-history":[{"count":0,"href":"https:\/\/racs.es\/en\/wp-json\/wp\/v2\/posts\/859\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/racs.es\/en\/wp-json\/wp\/v2\/media\/862"}],"wp:attachment":[{"href":"https:\/\/racs.es\/en\/wp-json\/wp\/v2\/media?parent=859"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/racs.es\/en\/wp-json\/wp\/v2\/categories?post=859"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/racs.es\/en\/wp-json\/wp\/v2\/tags?post=859"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}