
<p>
  This blog walk through how to use Swagger / OpenAPI to add API document to
  Next.js, a node.js framework. It will cover how to create to API at Next.js
  and add API Document with Swagger by swagger-jsdoc and&nbsp; swager-ui-react.
</p>
<h2>Setup Next.js</h2>
<p>
  You can reference Next.js' official document to get more detail about setup
  Next.js, in this blog we'll set up Next.js with TypeScript.&nbsp;&nbsp;
</p>
<p>
  After running the command at your terminal, follow the steps to finish setup
  the default code.&nbsp;
</p>
<pre class="language-bash"><code>npx create-next-app --typescript</code></pre>
<h3>Install dependencies packages for integrating with Swagger for Next.js</h3>
<p>
  Here, we'll install a list of packages that require to setup swagger API
  document. We'll install <code>swagger-ui-react</code> which use for create
  swagger UI page, use <code>@types/swagger-ui-react</code> since we start
  typescript with next.js, finally we use <code>swagger-jsdoc</code>for generate
  document from the code.&nbsp;
</p>
<pre class="language-bash"><code>npm install --save swagger-ui-react
npm install --save-dev @types/swagger-ui-react swaggerj-jsdoc</code></pre>
<h2>Create API at Next.js</h2>
<p>
  Once we setup the Next.js with default setting, we'll create following simple
  APIs so later we can add swagger to it.&nbsp;
</p>
<ul>
  <li>get all product list - [GET] /product</li>
  <li>get product by id - [GET] /product/:id</li>
  <li>create product - [POST] /product</li>
  <li>update product by id - [PUT] /product/:id</li>
  <li>delete product by id - [DELETE] /product/:id</li>
</ul>
<p>
  First we create this product service to have CRUD function for the product
  services. As, you can see this ProductService has deleteProduct,
  updateProduct, addProduct, getProductById and getAllProducts. We will use
  these service behind our Next.js API.&nbsp;
</p>
<pre class="language-javascript"><code>nterface Product {
    id: number;
    name: String;
    price: number;
}

class ProductService {

    products: Product[];

    private static instance: ProductService;

    private constructor() {
        this.products = [{
            id: 1,
            name: 'apple',
            price: 2
        }, {
            id: 2,
            name: 'banana',
            price: 1.5
        }];
    }

    public static Instance(): ProductService {
        if (!ProductService.instance) {
            ProductService.instance = new ProductService();
        }

        return ProductService.instance;
    }

    getAllProducts(): Product[]  {
        return this.products;
    }

    getProductById(id: number): Product | undefined {
        let result = this.products.filter(_ =&gt; _.id === id);
        if (result.length &gt; 0) {
            return result[0];
        }
        return undefined;
    }

    addProduct(product: Product) {
        let maxId = Math.max(...this.products.map((x) =&gt; x.id));
        
        this.products.push({
            id: ++maxId,
            name: product.name,
            price: product.price
        });

        return this.products;
    }

    updateProduct(id: number, newProduct: Product) : Product | undefined{
        let result = this.products.find(_ =&gt; _.id === id);
        if (!result) {
            return undefined;
        }

        result.name = newProduct.name;
        result.price = newProduct.price;

        return result;
    }

    deleteProduct(id: number) : Product[] | undefined{
        let index = this.products.findIndex(_ =&gt; _.id === id);
        if (!index) {
            return undefined;
        }

        this.products.splice(index, 1);

        return this.products;
    }
}

export default ProductService;</code></pre>
<h2>Create API</h2>
<p>
  First, we'll create <code>index.ts</code> file under api/product folder, this
  file will handler HTTP Get which will return all the products, POST will
  handler add new product to the existing product service.
</p>
<pre class="language-javascript"><code>export default function handler(
  req: NextApiRequest,
  res: NextApiResponse&lt;any&gt;
) {
  
  if (req.method === 'GET') {
    res.status(200).json(ProductService.Instance()
    .getAllProducts());
  }
  else if (req.method === 'POST') {
    res.status(200).json(
      ProductService.Instance()
      .addProduct(req.body));
      ;
  }  
}</code></pre>
<p>
  Next, we'll create <code>[id].ts</code> to handler dynamic Next.js API. This
  file, will be handler our update, delete and find by the product id
  APIs.&nbsp;
</p>
<pre class="language-javascript"><code>export default function handler(
  req: NextApiRequest,
  res: NextApiResponse&lt;any&gt;
) {
  
  const {query} = req;

  if (req.method === 'DELETE') {
    res.status(200).json(
      ProductService.Instance()
      .deleteProduct(+query.id));
      ;
  }
  else if (req.method === 'GET') {
    res.status(200).json(
      ProductService.Instance()
      .getProductById(+query.id))
      ;
  }  
  else if (req.method === 'PUT') {
    res.status(200).json(
      ProductService.Instance()
      .updateProduct(+query.id, req.body));
      ;
  }  
}</code></pre>
<h2>Verify the API</h2>
<p>
  At this point, if you run the following URL, you should be able to see the API
  response.
</p>
<p>
  <img
    src="https://d1p0mp3f1fx0hz.cloudfront.net/upload/2022/1/r1GHg1jCLEK7zeTJ3rSjZ3-153mzc3nb9520220110233250/750-153mzc3nb9520220110233250.png"
    alt="Responsive image"
  />
</p>
<h2>Add Swagger Javascript Comment</h2>
<p>
  This is actually import part to use Swagger UI at Next.js, you write the
  swagger base on the swagger API specification's YAML file format. Later, the
  swagger-jsdoc will read this and generate the swagger.json file for UI to
  use.&nbsp;
</p>
<p>Add this comment to the /api/product's index.ts file.&nbsp;</p>
<pre class="language-javascript"><code>/** 
 * @swagger 
 * /api/product:
 *   get: 
 *     tags:
 *          - Products
 *     description: Get all Product 
 *     responses:  
 *       200: 
 *         description: Success  
 */ </code></pre>
<h2>Add Swagger to Next.js</h2>
<p>
  Now, since the API is ready we can start setup our swagger at Next.js. First,
  I would like to show the swagger UI when user type /swagger. So, under the
  pages folder, created swagger.tsx file.&nbsp;
</p>
<p>
  So we you type the <strong>/swagger,</strong> Next.js will try to render
  following page. The page itself is from the Library
  <code>swagger-ui-react</code> package. It has depend on the swagger.json file,
  which we'll create later.&nbsp;
</p>
<p>
  Also, you can see that we import the <code>swagger-ui.css</code> from the
  <code>swagger-ui-react</code> libaray, if you have custom css style you can
  import your style as well.&nbsp;
</p>
<pre class="language-javascript"><code>import { NextPage } from "next";
import SwaggerUI from "swagger-ui-react";
import "swagger-ui-react/swagger-ui.css";

const Home: NextPage = () =&gt; {
  return &lt;SwaggerUI url="/swagger.json"&gt;hi&lt;/SwaggerUI&gt;;
};
export default Home;</code></pre>
<h3>Create swagger.json as part of build command</h3>
<p>
  Following command swagger will run the swagger-jsdoc task which will create
  swagger API specification base on the javascript document comment, then the
  swagger UI will use this json file to build the UI. So as you can see from
  following once create the swagger.json file I move it to the public folder.
</p>
<pre class="language-bash"><code> "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "swagger": "swagger-jsdoc -d swaggerConfig.js &amp;&amp; mv swagger.json ./public"
  },</code></pre>
<h2>That's should be All</h2>
<p>
  After above setup, write API, add API document comment, setup swagger at
  Next.js, you should be able to see following swagger API document page. Now,
  you can continue to add your API, add the comment base for each API, then
  you'll have this centralize API document to see all the API you have
  created.&nbsp;
</p>
<p>
  <img
    src="https://d1p0mp3f1fx0hz.cloudfront.net/upload/2022/1/uHgCecU8xgtU8Vz3cZfDzd-1p6ervh7ij520220110234502/750-1p6ervh7ij520220110234502.png"
    alt="Responsive image"
  />
</p>
<h2>Conclusion</h2>
<p>
  Swagger, Open API is a popular and easy way to setup API documents, with API
  documents you can easy to review all documents run the API check the API
  specification about support request or response object, test the API.&nbsp;
</p>
<p>
  All the code mentioned here, you can check at here
  <a
    href="https://github.com/keke78ui9/Sample-Code-For-Swagger/tree/master/swagger-expressjs"
    >Github</a
  >.
</p>
<p></p>


This blog walk through how to use Swagger / OpenAPI to add API document to Next.js, a node.js framework. It will cover how tocreate to API at Next.js and add API Document with Swagger by swagger-jsdoc and  swager-ui-react.

How to Setup Swagger with Next.js


<p>
  This blog walk through how to use Swagger / OpenAPI to add API document to the
  Express.js, node.js framework, it will cover how to create to API at
  Express.js and add API Document with Swagger by using OpenAPI 3.0
  specification.&nbsp;
</p>
<p>This blog mainly will convert in the following steps.</p>
<ol>
  <li>Create APIs with Express.js</li>
  <li>Setup Swagger documentation with OpenAPI 3.0</li>
</ol>
<h2>Setup Express.js</h2>
<p>
  At here, we'll set up the express.js with a list of dependencies packages
  needed for this blog.&nbsp;
</p>
<pre class="language-bash"><code>npm init -y
npm install --save express swagger-jsdoc swagger-ui-express
npm install --save-dev nodemon</code></pre>
<p>
  After running the above command, you should see
  <code>package.json</code> file created, should be something close to this.
</p>
<pre class="language-javascript"><code>{
  "name": "swagger-expressjs",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "dev": "nodemon index"
  },
  "keywords": [],
  "author": "keke78ui9",
  "license": "ISC",
  "dependencies": {
    "express": "^4.17.1",
    "swagger-jsdoc": "^6.1.0",
    "swagger-ui-express": "^4.2.0"
  },
  "devDependencies": {
    "nodemon": "^2.0.15"
  }
}</code></pre>
<p>
  So, let's take a look at these commands. First, you run this to create
  <code>package.json</code> file without default setting.&nbsp;
</p>
<pre class="language-bash"><code>npm init -y</code></pre>
<p>
  Here, we'll install the list of packages, express to Node.js Web Server, and
  will create API later as well. <code>swagger-jsdoc</code> and
  <code>swagger-ui-express</code> for setup swagger documentation.
</p>
<pre
  class="language-bash"
><code>npm install --save express swagger-jsdoc swagger-ui-express</code></pre>
<p>
  Lastly, install <code>nodemon</code> to reload server-side module after you
  made any change.&nbsp;
</p>
<pre class="language-bash"><code>npm install --save-dev nodemon</code></pre>
<h2>Setup Express.js Server</h2>
<p>
  Create an <code>index.js</code> file at the same directory of your
  package.json file, and add the following code, once you run the code you'll
  start the server with port 3106.&nbsp;
</p>
<pre class="language-javascript"><code>const express = require('express');

const app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

const product = require('./Routes/product');
app.use('/product', product);

app.listen(3106);</code></pre>
<h2>Create API at Express.js</h2>
<p>
  In this section, we create a file <code>product.js</code> and add the
  following APIs, create a temporary object to hold a list of products for demo
  purposes and you can list all products, or get by id, update or delete by the
  id.&nbsp;
</p>
<ul>
  <li>get all product list - [GET] /product</li>
  <li>get product by id - [GET] /product/:id</li>
  <li>create product - [POST] /product</li>
  <li>update product by id - [PUT] /product/:id</li>
  <li>delete product by id - [DELETE] /product/:id</li>
</ul>
<pre class="language-javascript"><code>const express = require('express');
const router = express.Router();

let products = [{
    id: 1,
    name: 'apple',
    price: 2
}, {
    id: 2,
    name: 'banana',
    price: 1.5
}];

router.get('/', (req, res) =&gt; {
    res.json(products);
});

router.get('/:id([0-9])', (req, res) =&gt; {
    let result = products.filter(_ =&gt; _.id == req.params.id);
    if (result.length &gt; 0) {
        res.json(result[0]);
    }
    else {
        badRequest(res);
    }
});

router.post('/', (req, res) =&gt; {

    if (req.body.name &amp;&amp; req.body.price) {
        
        let maxId = Math.max(...products.map((x) =&gt; x.id));

        products.push({
            id: ++maxId,
            name: req.body.name,
            price: req.body.price
        });
        res.json(products);
    }
    else {
        badRequest(res);
    }
});

router.put('/:id', (req, res) =&gt; {

    if (req.body.name &amp;&amp; req.body.price &amp;&amp; req.params.id) {
    
        let result = products.find(_ =&gt; _.id == req.params.id);
        if (!result) {
            badRequest(res);
        }

        result.name = req.body.name;
        result.price = req.body.price;
        
        res.json(products);
    }
    else {
        badRequest(res);
    }
});

router.delete('/:id', (req, res) =&gt; {
    let index = products.findIndex(_ =&gt; _.id == req.params.id);
    if (index === null) {
        badRequest(res);
    }

    products.splice(index, 1);
    res.json(products);
})</code></pre>
<h2>Verify the API</h2>
<p>
  At this point, if you run the following URL, you should be able to see the API
  response.
</p>
<p>
  <img
    src="https://d1p0mp3f1fx0hz.cloudfront.net/upload/2021/12/7iMzyJjBYpSwn9pJnRog5r-w7pfjpp4bl20211216002746/750-w7pfjpp4bl20211216002746.png"
    alt="Responsive image"
  />
</p>
<h2>Add Swagger UI Document</h2>
<h3>Create Swagger Option File</h3>
<p>
  We'll use swagger's OpenAPI version 3.0, following is a very simple setup for
  the main swagger configuration. Let's create a file called swaggerConfig.js
  and add the following code to it.&nbsp;
</p>
<pre
  class="language-javascript"
><code>// swagger OPENAPI specification https://swagger.io/specification/
const swaggerOptions = {
   swaggerDefinition: {  
        openapi: "3.0.0",     
        info: {  
            title:'Product API',  
            version:'1.0.0',
            description: 'how to use Product API'
        },
   },  
   apis:['./Routes/*.js'],      
};

module.exports = swaggerOptions;</code></pre>
<h3>Add Swagger configuration</h3>
<p>
  Here, we'll import these 2 modules, <code>swagger-ui-express</code> and
  <code>swagger-jsdoc</code>. Import the swagger config we created earlier and
  add the swagger configuration.&nbsp;
</p>
<pre
  class="language-javascript"
><code>const swaggerUI = require('swagger-ui-express');
const swaggerJSDoc = require('swagger-jsdoc');

const swaggerOptions = require('./swaggerConfig');

const swaggerDocs = swaggerJSDoc(swaggerOptions);  
app.use('/swagger', swaggerUI.serve, swaggerUI.setup(swaggerDocs));  
app.get('/swagger', function(req, res) {
   res.setHeader('Content-Type', 'application/json');
   res.send(swaggerDocs);
 });</code></pre>
<h2>Adding Swagger Comment as YAML File</h2>
<p>
  Now, we need the last step, cause if you type /swagger now, you won't see the
  swagger UI document yet. So let's add the comment to each API we created
  earlier. The following code is adding the document for the API to get all the
  products. After you add the following jsdoc comment, type the /swagger and
  then you should see the swagger UI page as below.&nbsp;
</p>
<pre class="language-javascript"><code>/** 
 * @swagger 
 * /product:
 *   get: 
 *     tags:
 *          - Products
 *     description: Get all Product 
 *     responses:  
 *       200: 
 *         description: Success  
 */ 
router.get('/', (req, res) =&gt; {
    res.json(products);
});</code></pre>
<p>
  Cool, right!? Now, you can use this swagger UI to view the detail of each API,
  execute the API at this UI as well.&nbsp;
</p>
<p>
  <img
    src="https://d1p0mp3f1fx0hz.cloudfront.net/upload/2021/12/9u2jZF82Yp11W74X7Gwznm-n27s0dskrh20211216004311/750-n27s0dskrh20211216004311.png"
    alt="Responsive image"
  />
</p>
<p>Now, the following is the code with the swagger comment for the APIs.</p>
<pre class="language-javascript"><code>** 
 * @swagger 
 * /product:
 *   get: 
 *     tags:
 *          - Products
 *     description: Get all Product 
 *     responses:  
 *       200: 
 *         description: Success  
 */ 
router.get('/', (req, res) =&gt; {
    res.json(products);
});

/** 
 * @swagger 
 * /product/{id}:
 *   get: 
 *      tags:
 *          - Products
 *      description: Get Product by ID
 *      produces:
 *          - application/json
 *      parameters:
 *          - name: id
 *            description: Product ID
 *            in: path
 *            required: true
 *            trype: integer
 *      responses:  
 *          200: 
 *              description: Success  
 */ 
router.get('/:id([0-9])', (req, res) =&gt; {
    let result = products.filter(_ =&gt; _.id == req.params.id);
    if (result.length &gt; 0) {
        res.json(result[0]);
    }
    else {
        badRequest(res);
    }
});

/** 
 * @swagger 
 * /product:
 *   post: 
 *     description: Add product
 *     requestBody:
 *       content:
 *         application/json:
 *            schema:
 *              type: object
 *              properties:
 *                  name:
 *                      type: string
 *                  price:
 *                      type: integer
 *     responses:  
 *       200: 
 *         description: Success  
 */ 
router.post('/', (req, res) =&gt; {


    if (req.body.name &amp;&amp; req.body.price) {
        
        let maxId = Math.max(...products.map((x) =&gt; x.id));

        products.push({
            id: ++maxId,
            name: req.body.name,
            price: req.body.price
        });
        res.json(products);
    }
    else {
        badRequest(res);
    }

});

/** 
 * @swagger 
 * /product/{id}:
 *   put: 
 *     description: update product by id
 *     parameters:
 *          - name: id
 *            description: Product ID
 *            in: path
 *            required: true
 *            trype: integer
 *          - name: product
 *            description: Product Object
 *            in: body
 *            required: true
 *            schema:
 *               $ref: '#/definitions/Product'
 *     responses:  
 *          200: 
 *              description: Success  
 */ 
router.put('/:id', (req, res) =&gt; {

    if (req.body.name &amp;&amp; req.body.price &amp;&amp; req.params.id) {
    
        let result = products.find(_ =&gt; _.id == req.params.id);
        if (!result) {
            badRequest(res);
        }

        result.name = req.body.name;
        result.price = req.body.price;
        
        res.json(products);
    }
    else {
        badRequest(res);
    }
});

/** 
 * @swagger 
 * /product/{id}:
 *   delete: 
 *     tags:
 *          - Products
 *     description: remove product by id
 *     parameters:
 *          - name: id
 *            description: Product ID
 *            in: path
 *            required: true
 *            trype: integer
 *     responses:  
 *          200: 
 *              description: Success  
 */ 
router.delete('/:id', (req, res) =&gt; {
    let index = products.findIndex(_ =&gt; _.id == req.params.id);
    if (index === null) {
        badRequest(res);
    }

    products.splice(index, 1);
    res.json(products);
})</code></pre>
<p>
  This blog doesn't cover all the aspects of the OpenAPI specification, for each
  term and variable you can reference the OpenAPI 3.0 document
  <a href="https://swagger.io/specification/">here</a>.&nbsp;
</p>
<h2>Conclusion</h2>
<p>
  Swagger, OpenAPI is a popular and easy way to set up API documents, if you
  create APIs you would like to know all the possible APIs with their
  documentation. Everything works great, except one thing I personally don't
  like is you have to use the YAML file to add a comment for each APIs, that
  process is manually be done, it could be error-prone, maybe there's something
  better to use for Express.js, I'll continue and write about it once I
  notice.&nbsp;
</p>
<p>
  All the code mentioned here, you can review at here
  <a
    href="https://github.com/keke78ui9/Sample-Code-For-Swagger/tree/master/swagger-expressjs"
    >Github</a
  >.
</p>
<p></p>


This blog walk through how to use Swagger / OpenAPI to add API document to the Express.js, node.js framework, it will cover how tocreate to API at Express.js and add API Document with Swagger by using OpenAPI 3.0 specification.

How to Setup Swagger OpenAPI with Express.js


<p>
  This blog is about how to set up Swagger / OpenAPI with Nest.js, a progressive
  Node.js framework, it will cover how to define a few sample APIs and how to
  enable Swagger UI at Nest.js.
</p>
<p>
  <img
    src="https://d1p0mp3f1fx0hz.cloudfront.net/upload/2021/12/32CDbRcaEajQgwXggRxgLz-3cuyrtgzyt20211205162214/750-3cuyrtgzyt20211205162214.png"
    alt="Responsive image"
  />
</p>
<h2>Setup Nest.js Project</h2>
<p>
  Here, first, we'll set up the Next.js project with typescript. Run the
  following command to clone the typescript template with Nest.js without the
  history.&nbsp;
</p>
<pre
  class="language-bash"
><code>degit https://github.com/nestjs/typescript-starter.git swagger-nestjs</code></pre>
<p>Install dependencies packages for setup swagger at Nest.js.</p>
<pre
  class="language-bash"
><code>npm install --save @nestjs/swagger swagger-ui-express</code></pre>
<h2>Setup Swagger UI at Next.js</h2>
<p>
  Here, we'll add code to set up swagger UI at the Next.js' main.ts, include
  what's the title, description of this API.
</p>
<pre
  class="language-javascript"
><code>import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('API example')
    .setDescription('The API description, add description here...')
    .setVersion('1.0')
    .addTag('Sample')
    .build();
    
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();</code></pre>
<h2>Create APIs</h2>
<p>
  At here, we'll create some sample code for the example API, add will add a few
  decorations to the API so later will display at the swagger UI.
</p>
<pre class="language-javascript"><code>@ApiTags('MyBlog')
@Controller('api/v1/sample')
export class SampleController {
  constructor(private readonly appService: AppService) {}

  @Get()
  @ApiResponse({ status: 200, description: 'show all sample data'})  
  @ApiResponse({ status: 500, description: 'exception'})  
  getAllSample(): string {
    return this.appService.getAllSamples();
  }

  @Get('/sample/:id')
  getSample(@Param('id') id: Number): string {
    return this.appService.getSampleById(id);
  }

  @Post('/sample')
  addSample(@Body() createModel: CreateSampleModel): CreateSampleModel {
    return this.appService.addSample(createModel);
  }

  @Put('/sample/:id')
  updateSample(@Param('id') id: Number, @Body() updateModel: any): string {
    return this.appService.updateSample(id, updateModel);
  }

  @Delete('/sample/:id')
  deleteSample(@Param('id') id: Number): string {
    return this.appService.deleteSample(id);
  }
}</code></pre>
<p>
  For instance, the following decorator for the API indicates that a list of
  HTTP status codes will return by this API, an endpoint, where consume the API,
  can handle HTTP response status code accordingly.&nbsp;
</p>
<pre
  class="language-javascript"
><code>  @ApiResponse({ status: 200, description: 'show all sample data'})  
  @ApiResponse({ status: 500, description: 'exception'})  
  getAllSample(): string {
    return this.appService.getAllSamples();
  }</code></pre>
<h2>Run the App</h2>
<p>
  Now, everything should be ready, following will install all the dependencies
  and start the Nest.js.
</p>
<pre class="language-bash"><code>npm install
npm run start</code></pre>
<p>
  While the application is running, browse and navigate to
  <a href="../api">http://localhost:3000/api</a>. You can see the documentation
  of your API's Swagger UI documentation.
</p>
<p>
  <img
    src="https://d1p0mp3f1fx0hz.cloudfront.net/upload/2021/12/69JpPkAKBx8HATufVLbDNM-1ot209a3z6v20211205233226/750-1ot209a3z6v20211205233226.png"
    alt="Responsive image"
  />
</p>
<p>
  Now, this is how you can set up Swagger UI for the Nest.js application. All
  the code here you can reference
  <a
    href="https://github.com/keke78ui9/Sample-Code-For-Swagger/tree/master/swagger-nestjs"
    >here</a
  >.
</p>


This blog is about how to setup Swagger / OpenAPI with Nest.js, a progressive Node.js framework, it will cover how to define fewsample API and how to enable Swagger UI at Nest.js.

How to Setup Swagger with Nest.js


<p>
  This walkthrough turtorial is about how to setup Swagger with ASP.NET MVC API
  by using Visual Studio 2015, also provide steps of how to customize the
  swagger UI.&nbsp;
</p>
<h2>What's Swagger?</h2>
<p>
  Swagger could provide more rich documents for your API, but that's not it, it
  provides how to design tests and documentation about your API. Although, this
  blog just focuses on how to set up Swagger UI on Visual Studio 2015's ASP.NET
  API project. ASP.NET MVC also has a Web API Helper page but unlike Swagger,
  which is more powerful with client generation, discoverable, and more
  developer support.&nbsp;
</p>
<p>
  This blog will show how to use Swagger to ASP.NET MVC API project and provide
  a list of how to.
</p>
<blockquote>
  <p>
    With a Swagger-enabled API, you get interactive documentation, client SDK
    generation and discoverability.
  </p>
</blockquote>
<pre class="language-xml"><code>Install-Package Swashbuckle
</code></pre>
<p>Following are few information relative with Swagger.</p>
<ul>
  <li>
    <a href="http://swagger.io/" target="_blank" rel="noopener">swagger.io</a>
  </li>
  <li>
    <a
      href="https://github.com/domaindrivendev/Swashbuckle"
      target="_blank"
      rel="noopener"
      >Swashbuckle</a
    >
  </li>
  <li>
    <a
      href="https://github.com/swagger-api/swagger-codegen/tree/master/samples"
      target="_blank"
      rel="noopener"
      >swagger-codegen</a
    >
  </li>
  <li>
    <a
      href="https://github.com/swagger-api/swagger-ui"
      target="_blank"
      rel="noopener"
      >swagger-ui</a
    >
  </li>
  <li>
    <a
      href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md"
      target="_blank"
      rel="noopener"
      >OpenAPI Specification</a
    >
  </li>
</ul>
<h2>Use Azure API App template with Swagger</h2>
<p>
  You can use Swagger with Visual Studio 2015, ASP.NET 4.5.2 Templates. Once you
  use Visual Studio and create a web application by template Azure API App, at
  your solution you should see the following Swagger at the package file.
</p>
<p>
  <img
    class="img-responsive"
    src="http://res.cloudinary.com/dmwrakaup/image/upload/v1458931625/vrtczaiykyxoxtecgloc.png"
    alt=""
  />
</p>
<p>
  You will find the NuGet library <code>Swashbuckle</code>, that .NET version of
  Swagger, if you want to use the latest NuGet version. You can use NuGet to
  uninstall the package and install the latest NuGet package again.
</p>
<p>
  <img
    class="img-responsive"
    src="https://d1p0mp3f1fx0hz.cloudfront.net/_dp4q0c174.png"
    alt=""
  />
</p>
<h3>
  <code>SwaggerConfig</code> and <code>EnableSwaggerUi</code> and basic
  configuration
</h3>
<p>
  After installing Swashbuckle, you will see a SwaggerConfig under your
  App_Start folder. This <code>SwaggerConfig</code> is the start point to enable
  Swagger. At the following, if you have already contained, then your setup is
  done. We should see the API document written by Swagger.
</p>
<pre
  class="language-csharp"
><code>[assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]

namespace WebApplication1
{
    public class SwaggerConfig
    {
        public static void Register()
        {
            var thisAssembly = typeof(SwaggerConfig).Assembly;

            GlobalConfiguration.Configuration 
                
                .EnableSwagger(c =&gt;
                    // {...
                    // this will enable swagger UI
                .EnableSwaggerUi(c =&gt;
</code></pre>
<h3>
  Build the solution and check the URL
  <code>{yoururl}/swagger or {yoururl/swagger/ui/index</code>
</h3>
<p>
  Boom!!!, you should be able to see the following swagger UI document page. I
  have two Web APIs, <code>TestController</code> and
  <code>ValuesController. </code>As you can see, it contains a search feature
  and you can try it out!!?
</p>
<p>
  <img
    class="img-responsive"
    src="http://res.cloudinary.com/dmwrakaup/image/upload/v1458932570/vbbqw3dh7xbalqxmxlyd.png"
    alt=""
  />
  <img
    class="img-responsive"
    src="https://d1p0mp3f1fx0hz.cloudfront.net/_3cxww0sfn.png"
    alt=""
  />
</p>
<p>
  However, I also got the following question when I first see these pages
  generated by Swagger.
</p>
<ul>
  <li>Can I change this API document's UI, including logo, stylesheet?</li>
  <li>Can I add javascript to this?</li>
  <li>Can I change the URL instead of /swagger?</li>
  <li>Can I add my own page to this auto-generated page?</li>
  <li>Can I make certain Web API does not show?</li>
  <li>
    Can I turn the swagger's API documents off at production, but only in
    development?
  </li>
</ul>
<p>
  I might not cover all these questions I have in my mind but will give them a
  try and list them here.
</p>
<h3>Can I Use a customized stylesheet for Swagger?</h3>
<p>
  Let's assume I want to change the following style, which changes the header
  background color to <code>#704C8F</code>.
</p>
<h3>1. CSS file</h3>
<pre class="language-css"><code>.swagger-section #header {
    background-color: #704C8F;
    padding: 14px;
}
</code></pre>
<h3>2. SwaggerConfig</h3>
<pre class="language-csharp"><code>.EnableSwaggerUi(c =&gt;                   {
c.InjectStylesheet(Assembly.GetAssembly(typeof(WebApiApplication)), "WebApplication2.styles.swagger_test.css");
</code></pre>
<h3>3. Global.ascx</h3>
<h4>How the WebApiApplication looks like</h4>
<p>
  The SwaggerConfig's InjectStylesSheet's first parameter need to pass the
  current application's assembly, the second parameter is a little tricky. The
  filename <code>WebApplication2.styles.swagger_test.css</code>is
  <code>Project Folder name</code>.<code>{folder name}</code> and the file name.
</p>
<pre class="language-csharp"><code>namespace WebApplication2
{
    public class WebApiApplication : System.Web.HttpApplication
    {
        protected void Application_Start()
        {
            AreaRegistration.RegisterAllAreas();
            GlobalConfiguration.Configure(WebApiConfig.Register);
            RouteConfig.RegisterRoutes(RouteTable.Routes);
        }
    }
}</code></pre>
<h4>4. styles file location</h4>
<p>
  Also, this is very important, you have made the file BuildAction an Embedded
  Resource.
</p>
<pre class="language-csharp"><code></code></pre>
<h4>4. After 1 - 4 steps, how the page looks like</h4>
<p>
  <img
    class="img-responsive"
    src="http://res.cloudinary.com/dmwrakaup/image/upload/v1458968917/vetiqfmu4mizsfyolm2h.png"
    alt=""
  />
</p>
<p>&nbsp;</p>
<h3>Can I add my own Javascript file to Swagger API documents?</h3>
<p>
  You are able to do it as follows, assume you have a javascript file like this.
</p>
<p>1. Javascript</p>
<pre class="language-javascript"><code>(function () {
    function init() {

        console.info("init for my swagger function");

        $("#explore").click(function () {
            alert("you clicked explore");
        });
    }

    init();
})();</code></pre>
<h4>2. Javascript file location and Build Action Property</h4>
<pre class="language-javascript"><code>
</code></pre>
<h4>3. SwaggerConfig class</h4>
<p>set the javascript path as string type like following.</p>
<pre
  class="language-csharp"
><code>   var myAssembly = Assembly.GetAssembly(typeof(WebApiApplication));
   c.InjectJavaScript(myAssembly, "WebApplication2.js.swagger_test.js");
</code></pre>
<h4>4. Done, check the page</h4>
<p>
  When the page load, you can see the javascript console message, now you can
  add javascript to the page, my next question is can I change the default Html?
</p>
<p>
  <img
    class="img-responsive"
    src="http://res.cloudinary.com/dmwrakaup/image/upload/v1458969860/h3novy9llbwau4kearez.png"
    alt=""
  />
</p>
<h3>
  Now, we know we can change javascript, CSS, can we change the entire HTML?
</h3>
<p>
  Yes, and the main feature will still work if you use the swagger's existing
  javascript. Following is how we can do it.
</p>
<h4>1. Html Files</h4>
<p>
  This time I want to add two HTML, after creating these HTML you also have to
  change Build Action as Embedded Resource again.
</p>
<p>
  <img
    class="img-responsive"
    src="http://res.cloudinary.com/dmwrakaup/image/upload/v1458971711/evgs4ci6wclqwpqpirxg.png"
    alt=""
  />
</p>
<p>swagger_test.html</p>
<pre class="language-html"><code>&lt;h3&gt;Bomm!!!!&lt;/h3&gt;
</code></pre>
<p>OtherVersion.html</p>
<pre class="language-html"><code>&lt;!DOCTYPE html&gt;
&lt;html&gt;
&lt;head&gt;
    &lt;meta charset="UTF-8"&gt;
    &lt;title&gt;Swagger UI My Own Version&lt;/title&gt;
    &lt;link rel="icon" type="image/png" href="images/favicon-32x32-png" sizes="32x32" /&gt;
    &lt;link rel="icon" type="image/png" href="images/favicon-16x16-png" sizes="16x16" /&gt;
    &lt;link href='css/typography-css' media='screen' rel='stylesheet' type='text/css' /&gt;
    &lt;link href='css/reset-css&amp;#
39; media='screen' rel='stylesheet' type='text/css' /&gt;
    &lt;link href='css/screen-css' media='screen' rel='stylesheet' type='text/css' /&gt;
    &lt;link href='css/reset-css' media='print' rel='stylesheet' type='text/css' /&gt;
    &lt;link href='css/print-css' media='print' rel='stylesheet' type='text/css' /&gt;
    &lt;link href='ext/WebApplication2-styles-swagger_test-css' media='screen' rel='stylesheet' type='text/css' /&gt;

    &lt;script src='lib/jquery-1-8-0-min-js' type='text/javascript'&gt;&lt;/script&gt;
    &lt;script src='lib/jquery-slideto-min-js' type='text/javascript'&gt;&lt;/script&gt;
    &lt;script src='lib/jquery-wiggle-min-js' type='text/javascript'&gt;&lt;/script&gt;
    &lt;script src='lib/jquery-ba-bbq-min-js' type='text/javascript'&gt;&lt;/script&gt;
    &lt;script src='lib/handlebars-2-0-0-js' type='text/javascript'&gt;&lt;/script&gt;
    &lt;script src='lib/underscore-min-js' type='text/javascript'&gt;&lt;/script&gt;
    &lt;script src='lib/backbone-min-js' type='text/javascript'&gt;&lt;/script&gt;
    &lt;script src='swagger-ui-min-js' type='text/javascript'&gt;&lt;/script&gt;
    &lt;script src='lib/highlight-7-3-pack-js' type='text/javascript'&gt;&lt;/script&gt;
    &lt;script src='lib/jsoneditor-min-js' type='text/javascript'&gt;&lt;/script&gt;
    &lt;script src='lib/marked-js' type='text/javascript'&gt;&lt;/script&gt;
    &lt;script src='lib/swagger-oauth-js' type='text/javascript'&gt;&lt;/script&gt;

    &lt;!-- Some basic translations --&gt;
    &lt;!-- &lt;script src='lang/translator.js' type='text/javascript'&gt;&lt;/script&gt; --&gt;
    &lt;!-- &lt;script src='lang/ru.js' type='text/javascript'&gt;&lt;/script&gt; --&gt;
    &lt;!-- &lt;script src='lang/en.js' type='text/javascript'&gt;&lt;/script&gt; --&gt;

    &lt;script type="text/javascript"&gt;
    $(function () {
      var url = window.location.search.match(/url=([^&amp;]+)/);
      if (url &amp;&amp; url.length &gt; 1) {
        url = decodeURIComponent(url[1]);
      } else {
        url = "http://petstore.swagger.io/v2/swagger.json";
      }

      // Get Swashbuckle config into JavaScript
      function arrayFrom(configString) {
        return (configString !== "") ? configString.split('|') : [];
      }

      function stringOrNullFrom(configString) {
        return (configString !== "null") ? configString : null;
      }

      window.swashbuckleConfig = {
        rootUrl: 'http://localhost:65343',
        discoveryPaths: arrayFrom('swagger/docs/v1'),
        booleanValues: arrayFrom('true|false'),
        validatorUrl: stringOrNullFrom('http://localhost:65343/validator'),
        customScripts: arrayFrom('ext/WebApplication2-js-swagger_test-js'),
        docExpansion: 'none',
        oAuth2Enabled: ('false' == 'true'),
        oAuth2ClientId: '',
        oAuth2ClientSecret: '',
        oAuth2Realm: '',
        oAuth2AppName: '',
        oAuth2ScopeSeperator: ' ',
        oAuth2AdditionalQueryStringParams: JSON.parse('{}')
      };

      // Pre load translate...
      if(window.SwaggerTranslator) {
        window.SwaggerTranslator.translate();
      }
      window.swaggerUi = new SwaggerUi({
        url: swashbuckleConfig.rootUrl + "/" + swashbuckleConfig.discoveryPaths[0],
        dom_id: "swagger-ui-container",
        booleanValues: swashbuckleConfig.booleanValues,
        onComplete: function(swaggerApi, swaggerUi){
          if (typeof initOAuth == "function" &amp;&amp; swashbuckleConfig.oAuth2Enabled) {
            initOAuth({
              clientId: swashbuckleConfig.oAuth2ClientId,
              clientSecret: swashbuckleConfig.oAuth2ClientSecret,
              realm: swashbuckleConfig.oAuth2Realm,
              appName: swashbuckleConfig.oAuth2AppName,
              scopeSeparator: swashbuckleConfig.oAuth2ScopeSeperator,
              additionalQueryStringParams: swashbuckleConfig.oAuth2AdditionalQueryStringParams
            });
          }

          if(window.SwaggerTranslator) {
            window.SwaggerTranslator.translate();
          }

          $('pre code').each(function(i, e) {
            hljs.highlightBlock(e)
          });

          addApiKeyAuthorization();

          window.swaggerApi = swaggerApi;
          _.each(swashbuckleConfig.customScripts, function (script) {
            $.getScript(script);
          });
        },
        onFailure: function(data) {
          log("Unable to Load SwaggerUI");
        },
        docExpansion: swashbuckleConfig.docExpansion,
        jsonEditor: false,
        apisSorter: null, // default to server
        defaultModelRendering: 'schema',
        showRequestHeaders: false
      });

      if (window.swashbuckleConfig.validatorUrl !== '')
        window.swaggerUi.options.validatorUrl = window.swashbuckleConfig.validatorUrl;

      function addApiKeyAuthorization(){
        var key = encodeURIComponent($('#input_apiKey')[0].value);
        if (key &amp;&amp; key.trim() != "") {
          var apiKeyAuth = new SwaggerClient.ApiKeyAuthorization("api_key", key, "query");
            window.swaggerUi.api.clientAuthorizations.add("api_key", apiKeyAuth);
            log("added key " + key);
        }
      }

      $('#input_apiKey').change(addApiKeyAuthorization);

      // if you have an apiKey you would like to pre-populate on the page for demonstration purposes...
      /*
        var apiKey = "myApiKeyXXXX123456789";
        $('#input_apiKey').val(apiKey);
      */

      window.swaggerUi.load();

      function log() {
        if ('console' in window) {
          console.log.apply(console, arguments);
        }
      }
  });
    &lt;/script&gt;
&lt;/head&gt;

&lt;body class="swagger-section"&gt;
    &lt;h1&gt;Damn, I love this! Swagger!&lt;/h1&gt;

    &lt;div id="message-bar" class="swagger-ui-wrap" data-sw-translate&gt;&amp;nbsp;&lt;/div&gt;
    &lt;div id="swagger-ui-container" class="swagger-ui-wrap"&gt;&lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;

</code></pre>
<h3>2. SwaggerConfig for Html</h3>
<pre>
      c.CustomAsset("swagger_test", myAssembly, "WebApplication2.html.swagger_test.html");
                        c.CustomAsset("OtherVersion", myAssembly, "WebApplication2.html.OtherVersion.html");
</pre>
<h3>3. That's it, let's check the browser.</h3>
<p>
  Now, you're going to ask a question, what's the URL. I didn't figure it out at
  the first, but look like Swagger is using the file name as the URL. Since
  their default page is /swagger/ui/index, so my new files' URL will be
  <code>/swagger/ui/OtherVersion</code> and
  <code>/swagger/ui/swagger_test</code>
</p>
<p>
  Following is one of my new pages, OtherVersion. Isn't this so sweet? As a
  developer when you use other UI Framework if you can replace CSS, Javascript
  and HTML but keep their original logic. That's just fantastic.
</p>
<p>
  <img
    class="img-responsive"
    src="http://res.cloudinary.com/dmwrakaup/image/upload/v1458972150/uiblm9hoxxitxz1fgxls.png"
    alt=""
  />
</p>
<h3>Add .NET XML comment for swagger's API description</h3>
<p>
  ASP.NET WebAPI's default API helper document also looks for DLL's XML comment
  for description. We can do that in swagger too.
</p>
<h4>1. Project property</h4>
<p>
  The first thing you need to do is go to the project that contains the API
  controller to check the XML documentation file, so when building the solution
  visual studio will update the XML with comments you add to the class. Also,
  swagger later will read the XML's comment as a description of the API too.
</p>
<p>
  <img
    class="img-responsive"
    src="http://res.cloudinary.com/dmwrakaup/image/upload/v1459030325/o170ozq0mak76k8hfoqi.png"
    alt=""
  />
</p>
<h4>2. SwaggerConfig setting</h4>
<p>
  The next important thing is, swagger has not registered the API XML, you can
  add it as follows.
</p>
<pre
  class="language-csharp"
><code> c.IncludeXmlComments(string.Format(@"{0}\bin\APIDemo.XML", System.AppDomain.CurrentDomain.BaseDirectory));
</code></pre>
<p>
  Following are examples of the WebAPI controller and the API Model class' XML
  document.
</p>
<pre class="language-csharp"><code>/// &lt;summary&gt;
    /// my product
    /// &lt;/summary&gt;
    public class Product
    {
        /// &lt;summary&gt;
        /// product id
        /// &lt;/summary&gt;
        public Guid GuidId { get; set; }
        /// &lt;summary&gt;
        /// product Id
        /// &lt;/summary&gt;
        public int ProductId { get; set; }
        /// &lt;summary&gt;
        /// product name
        /// &lt;/summary&gt;
        public string ProductName { get; set; }
        /// &lt;summary&gt;
        /// product price
        /// &lt;/summary&gt;
        public decimal Price { get; set; }
        /// &lt;summary&gt;
        /// product unit
        /// &lt;/summary&gt;
        public int Unit { get; set; }
</code></pre>
<pre class="language-csharp"><code>/// &lt;summary&gt;
    /// ProductController API
    /// &lt;/summary&gt;
    public class ProductController : ApiController
    {
        /// &lt;summary&gt;
        /// products data
        /// &lt;/summary&gt;
        public static List&lt;Product&gt; Products
        {
            get
            {
                return new List&lt;Product&gt;
                {
                    new Product(Guid.NewGuid(), 122, "Product A", 300, 1),
                    new Product(Guid.NewGuid(), 333, "Product B", 400, 10),
                    new Product(Guid.NewGuid(), 444, "Product C", 500, 20),
                    new Product(Guid.NewGuid(), 555, "Product D", 600, 15),
                    new Product(Guid.NewGuid(), 777, "Product E", 700, 5)
                };
            }
        }

        /// &lt;summary&gt;
        ///  get values for products
        /// &lt;/summary&gt;
        /// &lt;returns&gt;&lt;/returns&gt;
        public IEnumerable&lt;Product&gt; Get()
        {
            return Products;
        }
</code></pre>
<h4>3. Done! Let's browser the API Document</h4>
<p>
  Now, we're done, after building the solution, you should see your XML comment
  add to the Csharp class at the Swagger API documentation page.
</p>
<p>
  <img
    class="img-responsive"
    src="https://d1p0mp3f1fx0hz.cloudfront.net/_iw664rs80.png"
    alt=""
  />
</p>
<h3>Conclusion</h3>
<p>
  Swagger with ASP.NET MVC will provide very powerful API documentation and it
  is very flexible.
</p>
<p>
  Check the
  <a
    href="https://github.com/keke78ui9/Sample-Code-For-Swagger/tree/master/swagger-aspnetmvc-2015"
    target="_blank"
    title="setup swagger ui to aspnet "
    rel="noopener"
    >Code</a
  >
  mentioned in this blog.
</p>


This walkthrough tutorial is about how to set up Swagger with ASP.NET MVC API by using Visual Studio 2015, also provides steps ofhow to customize the swagger UI.

Category OpenAPI

How to Setup Swagger with Next.js

How to Setup Swagger OpenAPI with Express.js

How to Setup Swagger with Nest.js

How to Setup and Customize Swagger with ASP.NET MVC