<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Davi Baltar on Medium]]></title>
        <description><![CDATA[Stories by Davi Baltar on Medium]]></description>
        <link>https://medium.com/@davibaltar?source=rss-d33ef19b0d7------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*90WzW8w2uWah2yesU2g05Q.jpeg</url>
            <title>Stories by Davi Baltar on Medium</title>
            <link>https://medium.com/@davibaltar?source=rss-d33ef19b0d7------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 08:20:26 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@davibaltar/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Documentação automática de APIs em Node.js com Swagger — Parte 2 (Usando OpenAPI v3)]]></title>
            <link>https://davibaltar.medium.com/documenta%C3%A7%C3%A3o-autom%C3%A1tica-de-apis-em-node-js-com-swagger-parte-2-usando-openapi-v3-cbc371d8c5ee?source=rss-d33ef19b0d7------2</link>
            <guid isPermaLink="false">https://medium.com/p/cbc371d8c5ee</guid>
            <category><![CDATA[nodejs]]></category>
            <category><![CDATA[swagger]]></category>
            <category><![CDATA[open-api]]></category>
            <category><![CDATA[autogen]]></category>
            <category><![CDATA[documentation]]></category>
            <dc:creator><![CDATA[Davi Baltar]]></dc:creator>
            <pubDate>Sun, 01 Oct 2023 01:59:41 GMT</pubDate>
            <atom:updated>2023-10-28T13:30:13.079Z</atom:updated>
            <content:encoded><![CDATA[<h3>Documentação automática de APIs em Node.js com Swagger — Parte 2 (Usando OpenAPI v3)</h3><p><strong>Documentação completa:</strong> <a href="https://swagger-autogen.github.io/">https://swagger-autogen.github.io</a></p><p>Escrever uma documentação Swagger no padrão OpenAPI nem sempre é uma tarefa fácil, mesmo com todo auxílio da documentação <a href="https://swagger.io/specification/v3">OpenAPI Specification</a>, todo ajuste no arquivo .json requer um certo esforço. Pensando nisso, a lib <a href="https://www.npmjs.com/package/swagger-autogen">swagger-autogen</a> vem com finalidade de facilitar a vida do desenvolvedor fazendo toda (ou boa parte) da geração da documentação. Este artigo é uma continuação do <a href="https://medium.com/swlh/automatic-api-documentation-in-node-js-using-swagger-dd1ab3c78284">Automatic API Documentation in Node.js Using Swagger</a> que escrevi um tempo atrás. A ideia agora é mostrar como gerar automaticamente uma documentação para o Swagger no padrão OpenAPI v3 através da lib <a href="https://www.npmjs.com/package/swagger-autogen">swagger-autogen</a>. Neste artigo eu também vou mostrar algumas opções avançadas que essa lib é capaz de fazer. Bom, sem muita enrolação, vamos direto ao ponto.</p><p>Antes de tudo, vamos criar um projeto básico. Para isso, dentro de uma pasta qualquer em seu computador, vamos iniciar o nosso projeto lá com o seguinte comando:</p><pre>npm init -y</pre><p>e em seguida, vamos instalar o swagger-autogen:</p><pre>npm install --save-dev swagger-autogen</pre><p>E vamos instalar também o <em>express</em>, <em>swagger-ui-express</em> e <em>body-parser</em> para nos auxiliar na criação de um servidor, na interpretação do .json gerado pelo swagger-autogen e no tratamento body, respectivamente:</p><pre>npm install express swagger-ui-express body-parser</pre><p>Lembrando que o swagger-autogen gera somente o arquivo .json com a especificações!</p><p>O nosso projeto então ficará com seguinte estrutura básica:</p><pre>|-- package.json<br>|-- swagger.js<br>|-- index.js<br>|-- endpoints.js</pre><p>No arquivo <em>index.js</em>, vamos implementar o nosso servidor, configurá-lo na porta 3000 e pedir que o <em>swagger-ui-express</em> exponha o endpoint &quot;/docs&quot; com a nossa documentação gerado no arquivo <em>swagger-output.json</em> pelo swagger-autogen, ficando da seguinte forma:</p><pre>const swaggerUi = require(&#39;swagger-ui-express&#39;);<br>const swaggerFile = require(&#39;./swagger-output.json&#39;);<br>const bodyParser = require(&#39;body-parser&#39;);<br>const express = require(&#39;express&#39;);<br>const app = express();<br><br>/* Middlewares */<br>app.use(bodyParser.json());<br>app.use(&#39;/docs&#39;, swaggerUi.serve, swaggerUi.setup(swaggerFile));<br><br>app.listen(3000, () =&gt; {<br>  console.log(&quot;API documentation: http://localhost:3000/docs&quot;);<br>});<br><br>/* Endpoints */<br>require(&#39;./endpoints&#39;)(app);</pre><p>O arquivo <em>swagger.js</em> vai ser responsável por conter informações que compõem nossa documentação como meta dados, <em>schemas</em>, etc, bem como chamar a função do swagger-autogen para gerar o arquivo .json. Então, no nosso arquivo <em>swagger.js</em> vamos escrever as seguintes linhas de código:</p><pre>const swaggerAutogen = require(&#39;swagger-autogen&#39;)({ openapi: &#39;3.0.0&#39; });<br><br>const doc = {<br>    info: {<br>        version: &quot;1.0.0&quot;,<br>        title: &quot;My API&quot;,<br>        description: &quot;Some description...&quot;<br>    },<br>    servers: [<br>        {<br>            url: &#39;http://localhost:3000&#39;<br>        }<br>    ],<br>    components: {<br>        schemas: {<br>            someBody: {<br>                $name: &quot;Jhon Doe&quot;,<br>                $age: 29,<br>                about: &quot;&quot;<br>            },<br>            someResponse: {<br>                name: &quot;Jhon Doe&quot;,<br>                age: 29,<br>                diplomas: [<br>                    {<br>                        school: &quot;XYZ University&quot;,<br>                        year: 2020,<br>                        completed: true,<br>                        internship: {<br>                            hours: 290,<br>                            location: &quot;XYZ Company&quot;<br>                        }<br>                    }<br>                ]<br>            },<br>            someEnum: {<br>                &#39;@enum&#39;: [<br>                    &quot;red&quot;,<br>                    &quot;yellow&quot;,<br>                    &quot;green&quot;<br>                ]<br>            }<br>        },<br>        securitySchemes:{<br>            bearerAuth: {<br>                type: &#39;http&#39;,<br>                scheme: &#39;bearer&#39;<br>            }<br>        }<br>    }<br>};<br><br>const outputFile = &#39;./swagger-output.json&#39;;<br>const endpointsFiles = [&#39;./endpoints.js&#39;];<br><br>swaggerAutogen(outputFile, endpointsFiles, doc).then(() =&gt; {<br>    require(&#39;./index&#39;);           // Your project&#39;s root file<br>});</pre><p>Não se assuste caso você não tenha entendido alguma das propriedades acima, vou falar de sobre elas no decorrer do artigo. Um ponto importe, repare que informamos nas opções de entrada da função do swagger-autogen a propriedade:</p><pre>{ openapi: &#39;3.0.0&#39; }</pre><p>Isso informa ao swagger-autogen que queremos a geração da documentação no padrão OpenAPI v3. Caso não informe nada, por padrão a lib cria a documentação no padrão Swagger 2.0.</p><p>Certo, agora vamos criar dois endpoints bem básicos no nosso arquivo <em>endpoints.js</em> e vamos verificar o que a lib é capaz de fazer inicialmente. Então, o nosso arquivo <em>endpoints.js</em> ficará da seguinte forma:</p><pre>module.exports = function (app) {<br><br>    app.get(&#39;/users/:id&#39;, (req, res) =&gt; {<br>        const filter = req.query.filter;<br><br>        const version = req.headers.version;<br><br>        return res.status(200).send(&quot;some data&quot;);<br>    });<br><br>    app.post(&#39;/users&#39;, (req, res) =&gt; {<br>        const { name, age } = req.body;<br><br>        return res.status(201).send();<br>    });<br><br>};</pre><p>Lembrando que neste artigo não estamos vendo sobre boas práticas de programação, padrão MVC, versionamento ou rotas. A ideia aqui é simplificar o máximo para que possamos ver só a parte da documentação.</p><p>Tudo pronto! Vamos executar o comando a seguir para que o swagger-autogen gere nosso arquivo .json (<em>swagger-output.json</em>). Para isso, vamos adicionar um script no arquivo <em>package.json</em>. Então nosso arquivo <em>package.json</em> ficará com a seguinte aparência:</p><pre>{<br>  &quot;name&quot;: &quot;example-swagger-autogen&quot;,<br>  &quot;version&quot;: &quot;1.0.0&quot;,<br>  &quot;description&quot;: &quot;Example showing the use of the swagger-autogen module.&quot;,<br>  &quot;main&quot;: &quot;index.js&quot;,<br>  &quot;readmeFilename&quot;: &quot;README.md&quot;,<br>  &quot;scripts&quot;: {<br>    &quot;start&quot;: &quot;node index.js&quot;,<br>    &quot;swagger&quot;: &quot;node swagger.js&quot;<br>  },<br>  &quot;dependencies&quot;: {<br>    &quot;express&quot;: &quot;^4.18.2&quot;,<br>    &quot;swagger-autogen&quot;: &quot;^2.23.6&quot;,<br>    &quot;swagger-ui-express&quot;: &quot;^4.6.3&quot;<br>  }<br>}</pre><p>Repare no:</p><pre>  &quot;scripts&quot;: {<br>    &quot;start&quot;: &quot;node index.js&quot;,<br>    &quot;swagger&quot;: &quot;node swagger.js&quot;<br>  },</pre><p>Feito isso, vamos executar o seguinte comando na raiz do projeto:</p><pre>npm run swagger</pre><p>Pronto. Ao acessarmos o endereço <a href="http://localhost:3000/docs,">http://localhost:3000/docs,</a> veremos o seguinte resultado:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/641/1*Xw4TpGFl7iWRm4U41Ubv6w.png" /></figure><p>Como podemos ver, a lib foi capaz de identificar o path e os parâmetros do <em>body</em>, <em>query</em> e <em>header</em> automaticamente. Olhando agora para o nosso arquivo de saída <em>swagger-output.json</em>, veremos o que a lib gerou:</p><pre>{<br>  &quot;openapi&quot;: &quot;3.0.0&quot;,<br>  &quot;info&quot;: {<br>    &quot;version&quot;: &quot;1.0.0&quot;,<br>    &quot;title&quot;: &quot;My API&quot;,<br>    &quot;description&quot;: &quot;Some description...&quot;<br>  },<br>  &quot;servers&quot;: [<br>    {<br>      &quot;url&quot;: &quot;http://localhost:3000&quot;<br>    }<br>  ],<br>  &quot;paths&quot;: {<br>    &quot;/users/{id}&quot;: {<br>      &quot;get&quot;: {<br>        &quot;description&quot;: &quot;&quot;,<br>        &quot;parameters&quot;: [<br>          {<br>            &quot;name&quot;: &quot;id&quot;,<br>            &quot;in&quot;: &quot;path&quot;,<br>            &quot;required&quot;: true,<br>            &quot;schema&quot;: {<br>              &quot;type&quot;: &quot;string&quot;<br>            }<br>          },<br>          {<br>            &quot;name&quot;: &quot;version&quot;,<br>            &quot;in&quot;: &quot;header&quot;,<br>            &quot;schema&quot;: {<br>              &quot;type&quot;: &quot;string&quot;<br>            }<br>          },<br>          {<br>            &quot;name&quot;: &quot;filter&quot;,<br>            &quot;in&quot;: &quot;query&quot;,<br>            &quot;schema&quot;: {<br>              &quot;type&quot;: &quot;string&quot;<br>            }<br>          }<br>        ],<br>        &quot;responses&quot;: {<br>          &quot;200&quot;: {<br>            &quot;description&quot;: &quot;OK&quot;<br>          }<br>        }<br>      }<br>    },<br>    &quot;/users&quot;: {<br>      &quot;post&quot;: {<br>        &quot;description&quot;: &quot;&quot;,<br>        &quot;responses&quot;: {<br>          &quot;201&quot;: {<br>            &quot;description&quot;: &quot;Created&quot;<br>          }<br>        },<br>        &quot;requestBody&quot;: {<br>          &quot;content&quot;: {<br>            &quot;application/json&quot;: {<br>              &quot;schema&quot;: {<br>                &quot;type&quot;: &quot;object&quot;,<br>                &quot;properties&quot;: {<br>                  &quot;name&quot;: {<br>                    &quot;example&quot;: &quot;any&quot;<br>                  },<br>                  &quot;age&quot;: {<br>                    &quot;example&quot;: &quot;any&quot;<br>                  }<br>                }<br>              }<br>            }<br>          }<br>        }<br>      }<br>    }<br>  },<br>  &quot;components&quot;: {<br>    &quot;schemas&quot;: {<br>      &quot;someBody&quot;: {<br>        &quot;type&quot;: &quot;object&quot;,<br>        &quot;properties&quot;: {<br>          &quot;name&quot;: {<br>            &quot;type&quot;: &quot;string&quot;,<br>            &quot;example&quot;: &quot;Jhon Doe&quot;<br>          },<br>          &quot;age&quot;: {<br>            &quot;type&quot;: &quot;number&quot;,<br>            &quot;example&quot;: 29<br>          },<br>          &quot;about&quot;: {<br>            &quot;type&quot;: &quot;string&quot;,<br>            &quot;example&quot;: &quot;&quot;<br>          }<br>        },<br>        &quot;required&quot;: [<br>          &quot;name&quot;,<br>          &quot;age&quot;<br>        ]<br>      },<br>      &quot;someResponse&quot;: {<br>        &quot;type&quot;: &quot;object&quot;,<br>        &quot;properties&quot;: {<br>          &quot;name&quot;: {<br>            &quot;type&quot;: &quot;string&quot;,<br>            &quot;example&quot;: &quot;Jhon Doe&quot;<br>          },<br>          &quot;age&quot;: {<br>            &quot;type&quot;: &quot;number&quot;,<br>            &quot;example&quot;: 29<br>          },<br>          &quot;diplomas&quot;: {<br>            &quot;type&quot;: &quot;array&quot;,<br>            &quot;items&quot;: {<br>              &quot;type&quot;: &quot;object&quot;,<br>              &quot;properties&quot;: {<br>                &quot;school&quot;: {<br>                  &quot;type&quot;: &quot;string&quot;,<br>                  &quot;example&quot;: &quot;XYZ University&quot;<br>                },<br>                &quot;year&quot;: {<br>                  &quot;type&quot;: &quot;number&quot;,<br>                  &quot;example&quot;: 2020<br>                },<br>                &quot;completed&quot;: {<br>                  &quot;type&quot;: &quot;boolean&quot;,<br>                  &quot;example&quot;: true<br>                },<br>                &quot;internship&quot;: {<br>                  &quot;type&quot;: &quot;object&quot;,<br>                  &quot;properties&quot;: {<br>                    &quot;hours&quot;: {<br>                      &quot;type&quot;: &quot;number&quot;,<br>                      &quot;example&quot;: 290<br>                    },<br>                    &quot;location&quot;: {<br>                      &quot;type&quot;: &quot;string&quot;,<br>                      &quot;example&quot;: &quot;XYZ Company&quot;<br>                    }<br>                  }<br>                }<br>              }<br>            }<br>          }<br>        }<br>      }<br>    },<br>    &quot;securitySchemes&quot;: {<br>      &quot;bearerAuth&quot;: {<br>        &quot;type&quot;: &quot;http&quot;,<br>        &quot;scheme&quot;: &quot;bearer&quot;<br>      }<br>    }<br>  }<br>}</pre><p>Podemos ver que a documentação se encontra no formato padrão OpenAPI. Bom, agora que temos o básico funcionando, vamos incrementar mais algumas coisas aos nossos endpoints e descobrir o que mais essa lib é capaz de fazer.</p><h3>Meta informações</h3><p>Vamos adicionar algumas informações como descrição, sumário e tags. Para fazer isso, vamos adicionar os seguintes comentários nos nossos endpoints:</p><pre>module.exports = function (app) {<br><br>    app.get(&#39;/users/:id&#39;, (req, res) =&gt; {<br>        /*<br>            #swagger.tags = [&#39;Users&#39;]<br>            #swagger.summary = &#39;Returns a user by id&#39;<br>            #swagger.description = &#39;This endpoint will return a user by id...&#39;<br>        */<br>        const filter = req.query.filter;<br><br>        const version = req.headers.version;<br><br>        return res.status(200).send(&quot;some data&quot;);<br>    });<br><br>    app.post(&#39;/users&#39;, (req, res) =&gt; {<br>        /*<br>            #swagger.tags = [&#39;Users&#39;]<br>            #swagger.summary = &#39;Create a new user&#39;<br>            #swagger.description = &#39;This endpoint will create a new user...&#39;<br>        */<br>        const { name, age } = req.body;<br><br>        return res.status(201).send();<br>    });<br><br>};</pre><p>Vamos executar novamente o comando <em>npm run swagger</em> e ver o resultado:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/641/1*0fda0jY9ztZ6qkmW7bngpQ.png" /></figure><h3>Body</h3><p>Ok, tudo gerado corretamente. Porém, se nós quisermos melhorar nosso <em>body</em> adicionando uma referência para o nosso <em>schema</em> <strong>someBody</strong> que está no arquivo <em>swagger.js</em>, será necessário um comentário do tipo <em>#swagger.requestBody</em> no nosso endpoint (<em>post</em>):</p><pre>    app.post(&#39;/users&#39;, (req, res) =&gt; {<br>        /*<br>            #swagger.tags = [&#39;Users&#39;]<br>            #swagger.summary = &#39;Create a new user&#39;<br>            #swagger.description = &#39;This endpoint will create a new user...&#39;<br>        */<br>        const { name, age } = req.body;<br><br>        /*  #swagger.requestBody = {<br>                required: true,<br>                content: {<br>                    &quot;application/json&quot;: {<br>                        schema: {<br>                            $ref: &quot;#/components/schemas/someBody&quot;<br>                        }  <br>                    }<br>                }<br>            } <br>        */<br><br>        return res.status(201).send();<br>    });</pre><p>Feito isso, após executarmos novamente, veremos o seguinte resultado:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/641/1*ifW0pXeieHpd2Pg39bQs0w.png" /></figure><p>Com isso, a lib substituiu o <em>body</em> identificado automaticamente e criou a referência para caminho &quot;/components/schemas/someBody&quot;. Veja também que os atributos <strong>name</strong> e <strong>age</strong> estão como obrigatórios. Isso se deve ao símbolo &quot;$&quot; que colocamos antes de cada um deles no objeto <strong>someBody</strong> dentro do arquivo <em>swagger.js</em>.</p><h3>Response</h3><p>Agora vamos adicionar algumas informações às nossas respostas, tais como descrição e referência para o nosso objeto <strong>someResponse</strong> que também está no arquivo <em>swagger.js</em>. Então, no nosso enpoint (<em>get</em>), vamos adicionar oum comentário do tipo <em>#swagger.responses[200]</em>:</p><pre>    app.get(&#39;/users/:id&#39;, (req, res) =&gt; {<br>        /*<br>            #swagger.tags = [&#39;Users&#39;]<br>            #swagger.summary = &#39;Returns a user by id&#39;<br>            #swagger.description = &#39;This endpoint will return a user by id...&#39;<br>        */<br>        const filter = req.query.filter;<br><br>        const version = req.headers.version;<br><br>        /*  #swagger.responses[200] = {<br>                description: &quot;Some description...&quot;,<br>                content: {<br>                    &quot;application/json&quot;: {<br>                        schema:{<br>                            $ref: &quot;#/components/schemas/someResponse&quot;<br>                        }<br>                    }           <br>                }<br>            }   <br>        */<br><br>        return res.status(200).send(&quot;some data&quot;);<br>    });</pre><p>Após executar nossa app, teremos o seguinte resultado:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/641/1*vhqUYg1kUmSMxVsPsL-3_A.png" /></figure><p>Legal! Vimos que ele adicionou a referência para o nosso someResponse e também disse que o conteúdo da resposta é do tipo <em>application/json</em>. Para mais informações sobre o <em>#swagger.responses</em>, dê uma olhada no seção <a href="https://swagger-autogen.github.io/docs/openapi-3/responses">Responses</a> da documentação oficial. Vamos agora para algumas opções avançadas.</p><h3>Autenticação</h3><p>Para adicionar autenticação aos nossos endpoints via Swagger, nós podemos fazer isso da seguinte maneira:</p><h4>Bearer Auth</h4><p>Para adicionar autenticação via Bearer Auth, nós adicionamos em nosso objeto <strong>doc</strong> no arquivo<em> swagger.js</em> a seguinte propriedade:</p><pre>const doc = {<br>  components: {<br>    ...<br>    securitySchemes:{<br>      bearerAuth: {<br>          type: &#39;http&#39;,<br>          scheme: &#39;bearer&#39;<br>      }<br>    }<br>  }<br>}</pre><p>Para que o endpoint identifique esse tipo de autenticação, vamos adicionar o comentário<em> #swagger.security</em> no endpoint em que queremos que a autenticação fique disponível (no nosso caso eu escolhi o <em>post</em>):</p><pre>    app.post(&#39;/users&#39;, (req, res) =&gt; {<br>        /*<br>            #swagger.tags = [&#39;Users&#39;]<br>            #swagger.summary = &#39;Create a new user&#39;<br>            #swagger.description = &#39;This endpoint will create a new user...&#39;<br><br>            #swagger.security = [{<br>                &quot;bearerAuth&quot;: []<br>            }] <br>        */<br><br>        const { name, age } = req.body;<br><br>        /*  #swagger.requestBody = {<br>                required: true,<br>                content: {<br>                    &quot;application/json&quot;: {<br>                        schema: {<br>                            $ref: &quot;#/components/schemas/someBody&quot;<br>                        }  <br>                    }<br>                }<br>            } <br>        */<br><br>        return res.status(201).send();<br>    });</pre><p>Após executarmos nossa app, teremos o resultado a seguir. Repare no símbolo de cadeado que apareceu no endpoint:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/641/1*ypeqG8wIYID2-2Ffof1ApQ.png" /></figure><p>Dessa forma agora podemos adicionar nosso token nas requisições do endpoint via Swagger para realizarmos a autenticação.</p><p>Outras formas de autenticação podem ser vistas na documentação oficial da lib em <a href="https://swagger-autogen.github.io/docs/openapi-3/authentication/">Authentication</a>.</p><h3>Enums</h3><p>Para adicionar enums em nosso endpoint é preciso utilizar a keyword <strong>&#39;@enum&#39; </strong>(as aspas fazem parte). É dessa forma que a lib entende que precisa interpretar o objeto como um enum. Para adicionar o enum, nós adicionamos em nosso objeto <strong>doc</strong> no arquivo <em>swagger.js</em> a seguinte propriedade <strong>someEnum</strong>:</p><pre>const doc = {<br>  components: {<br>    schemas: {<br>      ...<br>      someEnum: {<br>        &#39;@enum&#39;: [<br>            &quot;red&quot;,<br>            &quot;yellow&quot;,<br>            &quot;green&quot;<br>        ]<br>      }<br>    }<br>  }<br>}</pre><p>E no endpoint (<em>get</em>) vamos adicionar o seguinte comentário <em>#swagger.parameters[&#39;filter&#39;] </em>com a referência para o <strong>someEnum</strong>:</p><pre>    app.get(&#39;/users/:id&#39;, (req, res) =&gt; {<br>        /*<br>            #swagger.tags = [&#39;Users&#39;]<br>            #swagger.summary = &#39;Returns a user by id&#39;<br>            #swagger.description = &#39;This endpoint will return a user by id...&#39;<br>        */<br><br>        /*<br>            #swagger.parameters[&#39;filter&#39;] = {<br>                in: &#39;query&#39;,<br>                description: &#39;Some description...&#39;,<br>                schema: {<br>                    $ref: &#39;#/components/schemas/someEnum&#39;<br>                }<br>            }<br>        */<br>        const filter = req.query.filter;<br><br>        const version = req.headers.version;<br><br>        /*  #swagger.responses[200] = {<br>                description: &quot;Some description...&quot;,<br>                content: {<br>                    &quot;application/json&quot;: {<br>                        schema:{<br>                            $ref: &quot;#/components/schemas/someResponse&quot;<br>                        }<br>                    }           <br>                }<br>            }   <br>        */<br><br>        return res.status(200).send(&quot;some data&quot;);<br>    });</pre><p>E após executarmos a app, teremos o seguinte resultado:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/641/1*McSBLw7EXHOCkH1S8KC8-A.png" /></figure><p>Com isso dizemos que o parâmetro <em>filter</em> será um enum. Outras opções sobre o comentário <em>#swagger.parameters</em> podem ser vistas na seção <a href="https://swagger-autogen.github.io/docs/openapi-3/parameters">Parameters</a>.</p><h3>Concluindo</h3><p>Bom pessoal, por hoje é isso. A ideia aqui era trazer um pouco mais das possibilidades que o swagger-autogen pode fazer. A parte de OpenAPI da lib ainda não está 100% completa, mas os recursos existentes já contemplam muitos projetos. Mais informações sobre a lib é possível encontrar nos links a seguir:</p><p><strong>Documentação oficial:</strong> <a href="https://swagger-autogen.github.io/docs">https://swagger-autogen.github.io/docs</a></p><p><strong>Repositório (npmjs):</strong> <a href="https://www.npmjs.com/package/swagger-autogen">https://www.npmjs.com/package/swagger-autogen</a></p><p><strong>Repositório (github):</strong> <a href="https://github.com/swagger-autogen/swagger-autogen">https://github.com/swagger-autogen/swagger-autogen</a></p><p>Te vejo por aí!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=cbc371d8c5ee" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Automatic API documentation in Node.js Using Swagger]]></title>
            <description><![CDATA[<div class="medium-feed-item"><p class="medium-feed-image"><a href="https://medium.com/swlh/automatic-api-documentation-in-node-js-using-swagger-dd1ab3c78284?source=rss-d33ef19b0d7------2"><img src="https://cdn-images-1.medium.com/max/640/1*OW7Jj31Jpbc6QIhn_ucZfA.png" width="640"></a></p><p class="medium-feed-snippet">Original article in Portuguese Brazil: (Click here)</p><p class="medium-feed-link"><a href="https://medium.com/swlh/automatic-api-documentation-in-node-js-using-swagger-dd1ab3c78284?source=rss-d33ef19b0d7------2">Continue reading on The Startup »</a></p></div>]]></description>
            <link>https://medium.com/swlh/automatic-api-documentation-in-node-js-using-swagger-dd1ab3c78284?source=rss-d33ef19b0d7------2</link>
            <guid isPermaLink="false">https://medium.com/p/dd1ab3c78284</guid>
            <category><![CDATA[nodejs]]></category>
            <category><![CDATA[api]]></category>
            <category><![CDATA[documentation]]></category>
            <category><![CDATA[swagger]]></category>
            <category><![CDATA[automation]]></category>
            <dc:creator><![CDATA[Davi Baltar]]></dc:creator>
            <pubDate>Sat, 12 Sep 2020 16:24:43 GMT</pubDate>
            <atom:updated>2023-10-28T13:29:47.529Z</atom:updated>
        </item>
        <item>
            <title><![CDATA[Documentação automática de APIs em Node.js]]></title>
            <link>https://davibaltar.medium.com/documenta%C3%A7%C3%A3o-autom%C3%A1tica-de-apis-em-node-js-eb03041c643b?source=rss-d33ef19b0d7------2</link>
            <guid isPermaLink="false">https://medium.com/p/eb03041c643b</guid>
            <category><![CDATA[api]]></category>
            <category><![CDATA[swagger]]></category>
            <category><![CDATA[automatica]]></category>
            <category><![CDATA[nodejs]]></category>
            <category><![CDATA[documentação]]></category>
            <dc:creator><![CDATA[Davi Baltar]]></dc:creator>
            <pubDate>Fri, 17 Apr 2020 00:32:49 GMT</pubDate>
            <atom:updated>2023-10-28T13:30:55.516Z</atom:updated>
            <content:encoded><![CDATA[<h3>Documentação automática de APIs em Node.js com Swagger</h3><p><strong>Documentação completa:</strong> <a href="https://swagger-autogen.github.io/">https://swagger-autogen.github.io</a></p><p>Para quem desenvolve APIs em Node.js, seja a nível profissional ou não, sabe que manter a documentação do projeto atualizada não é uma tarefa fácil, ainda mais com prazos curtos e outras prioridades, a documentação acaba na maioria das vezes ficando desatualizada ou até mesmo ignorada. Para contornar isso, hoje eu vou falar sobre um módulo NPM para Node.js que realiza a documentação automaticamente para o Swagger sempre que o seu projeto é iniciado, sem que você tenha que ficar fazendo reparos ou retoques no arquivo .json do Swagger. O módulo em questão é o <a href="https://www.npmjs.com/package/swagger-autogen">swagger-autogen</a>.</p><p>O módulo swagger-autogen gera somente o arquivo .json do Swagger. Para interpretá-lo vamos contar com o auxílio do módulo swagger-ui-express e o Express.js para subir um servidor, deixando a documentação disponível em alguma porta. Ah! Mas só funciona com Express.js? Não, o módulo é independente de qualquer framework, MAS, alguns frameworks como o Express.js (e similares) vão ter algumas vantagens e nós veremos mais na frente quais são. Com o módulo é possível gerar a documentação de duas formas:</p><ol><li>Juntamente com o projeto, ou seja, toda vez que o projeto for iniciado, uma nova documentação é gerada, fazendo com que a mesma fique sempre atualizada.</li><li>Sem iniciar o projeto, ou seja, executando um script na raiz do projeto. Isso é similar ao npm test (testadores de plantão saberão…).</li></ol><p>A primeira eu achei mais interessante, pois ela mantém a documentação sempre atualizada quando alteramos o código. Mas vou falar de ambas as formas neste artigo!</p><p>A ideia do módulo é bem simples, basta indicar o arquivo de saída (.json) do Swagger, os arquivos contendo os endpoints, que são os arquivos onde estão as função .get(), .post(), etc., e um objeto contendo os detalhes da documentação, como: versão, título, descrição, schemes, etc., sendo que este último não é obrigatório, ele já possui alguns valores padrões. Um exemplo completo pode ser visto neste link: <a href="https://github.com/davibaltar/example-swagger-autogen">https://github.com/davibaltar/example-swagger-autogen</a>. Bom, chega de falar e vamos ao código!</p><p>Na sua forma mais simples, vou criar um projeto com a seguinte estrutura:</p><pre>|-- package.json<br>|-- swagger.js<br>|-- index.js<br>|-- endpoints.js</pre><p>Onde index.js é o arquivo raiz do seu projeto, ou seja, onde a execução é iniciada e endpoints.js é o arquivo que contém as funções .get, post, etc. O arquivo swagger.js ficará encarregado somente de chamar o módulo swagger-autogen para gerar a documentação.</p><p>Se você já utiliza o Express.js (ou similares) a boa notícia é que o módulo faz o reconhecimento automáticos dos métodos, path, status da respostas e do content-type do Header!. Se você não usa o Express.js ou similares, mais à frente falarei de como contornar isso.</p><p>Para fins didáticos, vou escrever o arquivo index.js, que conterá uma estrutura simples de um servidor, ficando da seguinte forma:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/e97ee037381b4d9a3f97975eff22b5f1/href">https://medium.com/media/e97ee037381b4d9a3f97975eff22b5f1/href</a></iframe><p>Lembrando que neste artigo não estamos vendo sobre segurança de APIs, boas práticas de programação, padrão MVC, versionamento ou rotas. A ideia aqui é simplificar o máximo para que possamos ver só a parte da documentação.</p><p>Olhando o arquivo index.js, temos na linha 4 a importação do arquivo no formato do Swagger (é este arquivo que o módulo swagger-autogen vai gerar), o servidor iniciado na linha 6, o middleware responsável por criar uma interface gráfica do Swagger na linha 9 e os endpoints na linha 11.</p><p>Nós iremos iniciar o arquivo endpoints.js com um único endpoint por enquanto, e no decorrer do artigo nós vamos incrementado mais coisas nele. Então, inicialmente o arquivo terá o seguinte conteúdo:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/e638d8f0579fc1c132f3f03f58ae55cd/href">https://medium.com/media/e638d8f0579fc1c132f3f03f58ae55cd/href</a></iframe><p>Agora é só chamar o módulo swagger-autogen para entrar em ação! Para isso, adicione no arquivo swagger.js o seguinte conteúdo:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/0f4c85835ac32e5cb2e113b0818809ce/href">https://medium.com/media/0f4c85835ac32e5cb2e113b0818809ce/href</a></iframe><p>No início do artigo eu disse que a documentação poderia ser gerada sem iniciar o projeto ou juntamente com o projeto. Agora vamos ver essas duas formas. Vamos começar pela documentação sendo gerada sem iniciar o projeto. Para isso, adicione no seu arquivo package.json um script chamado &quot;swagger-autogen&quot; com conteúdo &quot;node swagger.js&quot;. Dessa forma, os scripts do seu package.json deverão ficar da seguinte forma:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/19caec63582b25808cc8ccb2db4fc4fa/href">https://medium.com/media/19caec63582b25808cc8ccb2db4fc4fa/href</a></iframe><p>Tudo pronto! Vamos instalar as dependências executando o seguinte comando na raiz do projeto:</p><blockquote>npm install</blockquote><p>Após isso, para gerar a documentação sem iniciar o projeto, é só executar o seguinte comando na raiz do projeto:</p><blockquote>npm run swagger-autogen</blockquote><p>Gerado! O arquivo swagger_output.json será gerado e está pronto para subir! Mas e se eu quiser que esse arquivo seja gerado toda vez que eu iniciar o projeto? Para isso, basta fazer uma pequena alteração na função <em>swaggerAutogen(…)</em> do arquivo swagger.js, ficando da seguinte forma:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/fd7703abdce19755aa421c11874e5787/href">https://medium.com/media/fd7703abdce19755aa421c11874e5787/href</a></iframe><p>Onde index.js na linha 7 é o arquivo raiz do nosso projeto. Pronto! Basta executar novamente o comando:</p><blockquote>npm run swagger-autogen</blockquote><p>Com isso, a documentação será gerada e o projeto iniciado logo em seguida. Se você utiliza o Visual Studio Code, também poderá modificar seu arquivo launch.json para apontar para swagger.js ao invés de index.js, ganhando com isso a possibilidade de gerar a documentação e debugar seu código logo em seguida. O resultado você confere na imagem a seguir ou acessando: <a href="http://localhost:3000/doc">http://localhost:3000/doc</a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/665/1*DISV2xf5-RosJ6yLI80SjA.png" /></figure><p>Note que o módulo identificou automaticamente o método &quot;get&quot;, o path &quot;/users&quot;, o parâmetro &quot;id&quot; do path, o parametro &quot;filtro&quot; do query e o código &quot;404&quot; da resposta, adicionando ainda a descrição &quot;Not Found&quot;, automaticamente. Mas você pode estar se perguntando, e o título, a descrição, a versão e a descrição dos parâmetros? Calma, tem como adicionar isso tudo. Vamos turbinar nosso arquivo <em>swagger.js</em> deixando-o da seguinte forma:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/74829805bb52f452ea97f4b614387788/href">https://medium.com/media/74829805bb52f452ea97f4b614387788/href</a></iframe><p>Note que adicionamos um objeto chamado <strong>doc</strong> e passamos ele como o terceiro parâmetro da função <em>swaggerAutogen(…)</em>. Aos que já estão acostumados a escrever arquivos do Swagger, não há nada de novo alí, aos demais, segue uma pequena explicação sobre cada um dos parâmetros do objeto <strong>doc</strong>:</p><ul><li><strong>info:</strong> Informação gerais sobre a API, como: versão, título e descrição.</li><li><strong>host:</strong> Caminho e porta onde sua API será iniciada. No nosso caso, mantemos o padrão <em>http://localhost:3000</em>.</li><li><strong>basePath</strong>: Essa é a raiz do seu projeto. No nosso caso, mantemos o padrão &quot;/&quot;.</li><li><strong>schemes:</strong> São os protocolos utilizados. Apesar de não utilizarmos o HTTPS, eu o adicionei só para fins didáticos, mas você pode escolher HTTP e/ou HTTPS.</li><li><strong>consumes:</strong> Aqui é o tipo do conteúdo de entrada (famoso: Content-Type do header), ou seja, caso você receba um parâmetro pelo <em>body</em>, por exemplo, é o consumes que vai dizer ao Swagger se o tipo do dado é um JSON, XML ou outro.</li><li><strong>produces:</strong> Similar ao <em>consume</em>, o <em>produce</em> informa o tipo do conteúdo de saída, ou seja, informa ao Swagger se o tipo da resposta é um JSON, XML ou outro.</li><li><strong>tags:</strong> É um meta dado, ou seja, serão os grupos de endpoints dentro da sua API. Uma API pode ter, por exemplo, uma tag &quot;Users&quot; e uma tag chamada &quot;Books&quot; para separar os endpoints.</li><li><strong>securityDefinitions:</strong> Para quem faz uso de autenticação na API como JWT ou OAuth, essa opção permite realizar essas autenticações. OBS.: Nesse artigo não vou mostrar como fazer autenticação, esse é um assunto longo, simplesmente estou mostrando que o módulo aceita os parâmetros de segurança reconhecidos pelo Swagger.</li><li><strong>definitions:</strong> São as suas entradas e saídas. A diferença aqui é que o módulo realizar isso de uma forma mais simples, basta informar os parâmetros de entrada/saída do jeito como você deseja vê-los na documentação. Isso ajuda muito, porque quem já criou <em>definitions</em> na mão sabe como é se perder na hora de criar um objeto dentro de um array, por exemplo. Ao informar um objeto na <em>definition</em>, automaticamente o módulo já identifica o tipo e cria um exemplo para ele com base no parâmetro informado. OBS.: Para informar que um campo é obrigatório, basta adicionar o símbolo <strong>$</strong> antes do parâmetro (veja o objeto <em>AddUser</em> no código acima).</li></ul><p>Rode o código e veja como ficou:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/665/1*r4TgBy6n57mfGT6WzsGD_g.png" /></figure><p>Vamos aos endpoints! A forma de se comunicar com o módulo swagger-autogen é através da tag “#swagger” dentro de comentários (podendo ser do tipo // ou /* … */) e devem estar dentro de uma função. Neste artigo vou falar das principais tags utilizadas. As tags são auto descritivas, mas quem tiver alguma dúvida, pode conferir na documentação oficial do módulo (link no final do artigo).</p><p>Agora é hora de aprimorar o nosso pequeno gafanhoto! Vamos melhorar o nosso endpoint adicionando uma descrição e informando a qual grupo ele pertence (tags).</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/903784419810b411cdee67323648c04f/href">https://medium.com/media/903784419810b411cdee67323648c04f/href</a></iframe><p>Veja o resultado após executar o código:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/665/1*XUsc7WIlMR16AmD-FfOd3w.png" /></figure><p>Agora, vamos adicionar mais informações aos parâmetros id e filtro do nosso endpoint:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/b790433ba961352c0b086fb5ea4e9dce/href">https://medium.com/media/b790433ba961352c0b086fb5ea4e9dce/href</a></iframe><p>O resultado será:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/665/1*T_yfYcpAi0Z1r1YPpVPF1w.png" /></figure><p>Agora, vamos adicionar mais informações às respostas:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/417d6d3b6aee007ecd05002b4e1eda6c/href">https://medium.com/media/417d6d3b6aee007ecd05002b4e1eda6c/href</a></iframe><p>E o resultado será:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/665/1*3ivPa4ejum2NFhyjLK8XnQ.png" /></figure><p>Note que eu adicionei mais uma resposta, porém com status 200 e a definition <em>User</em> que escrevemos no arquivo swagger.js. Por fim, vamos adicionar um outro endpoint que use o método <em>POST</em>:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/ac227e53c983664e022f114ff929e0ab/href">https://medium.com/media/ac227e53c983664e022f114ff929e0ab/href</a></iframe><p>Ao final, o resultado será este:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/665/1*3op-qmCFFmJA6vjEyueeJw.png" /></figure><p>Existem outras possibilidades, como por exemplo: ignorar um determinado endpoint usando a tag &quot;#swagger.ignore = true&quot;, fazendo com que o endpoint não apareça na documentação. Mais recursos você confere direto na documentação oficial (link no final do artigo).</p><p>Para quem usa frameworks com um padrão diferente do Express.js, ou seja, os endpoints não são chamados no estilo foo.method(path, callback), é possível informar manualmente o início e o fim do endpoint com as tag &quot;#swagger.start&quot; e &quot;#swagger.end&quot;, respectivamente, além de ter que adicionar as tags &quot;#swagger.path&quot; e &quot;#swagger.method&quot;. O conteúdo entre as tags &quot;#swagger.start&quot; e &quot;#swagger.end&quot; são os mesmos vistos nos exemplos acima. Veja a seção &quot;Manual capture&quot; na documentação oficial (link no final do artigo) para ter mais detalhes sobre essas tags, mas vejam a seguir um exemplo simples de como reconhecer um endpoint manualmente. Considere uma função qualquer (aqui chamada de myFunction):</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/a031af2d49ce4506fae543042563f71f/href">https://medium.com/media/a031af2d49ce4506fae543042563f71f/href</a></iframe><p>E o resultado será:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/665/1*GMAhDamuI2dfTYPPhzo2rw.png" /></figure><p><strong>Update! Versão 2.0.0</strong></p><p>Com a versão 2.0.0 o módulo agora reconhece rotas e funções referenciadas automaticamente. Para quem tiver interesse, veja um exemplo do swagger-autogen com Router no link a seguir:</p><p><a href="https://github.com/davibaltar/example-swagger-autogen-with-router">https://github.com/davibaltar/example-swagger-autogen-with-router</a></p><p>Bom pessoal, a ideia deste artigo era somente passar uma ideia sobre o módulo e o que ele pode fazer. Quem quiser se aprofundar mais e conhecer outros recursos dele, acesse o link logo a baixo. É isso aí! Até uma próxima!</p><p>Módulo:</p><p><a href="https://www.npmjs.com/package/swagger-autogen">swagger-autogen</a></p><p>Link para o exemplo usando Router: <a href="https://github.com/davibaltar/example-swagger-autogen-with-router">https://github.com/davibaltar/example-swagger-autogen-with-router</a></p><p>Link para o exemplo do artigo: <a href="https://github.com/davibaltar/example-swagger-autogen">https://github.com/davibaltar/example-swagger-autogen</a>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=eb03041c643b" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>