
## Table of Contents

1. [Introduction](#introduction)
2. [Setup Next.js](#setup-nextjs)
3. [Create API at Next.js](#create-api-at-nextjs)
4. [Create API](#create-api)
5. [Verify the API](#verify-the-api)
6. [Add Swagger JavaScript Comment](#add-swagger-javascript-comment)
7. [Add Swagger to Next.js](#add-swagger-to-nextjs)
8. [Conclusion](#conclusion)

## Introduction

This blog walks through how to use Swagger / OpenAPI to add API documentation
to Next.js, a Node.js framework. It covers how to create APIs in Next.js and
add API documentation with Swagger using swagger-jsdoc and swagger-ui-react.

## Setup Next.js

You can reference Next.js's official documentation for more details about
setting up Next.js. In this blog, we'll set up Next.js with TypeScript.

After running the command in your terminal, follow the steps to finish setting
up the default code.

```
npx create-next-app --typescript
```

### Install Dependency Packages for Integrating Swagger with Next.js

Here, we'll install a list of packages required to set up the Swagger API
documentation. We'll install `swagger-ui-react`, which is used to
create the Swagger UI page. We use `@types/swagger-ui-react` since
we're using TypeScript with Next.js. Finally, we use `swagger-jsdoc`
to generate documentation from the code.

```
npm install --save swagger-ui-react
npm install --save-dev @types/swagger-ui-react swagger-jsdoc
```

## Create API at Next.js

Once we set up Next.js with default settings, we'll create the following
simple APIs so we can add Swagger to them later.

- get all product list - [GET] /product

- get product by id - [GET] /product/:id

- create product - [POST] /product

- update product by id - [PUT] /product/:id

- delete product by id - [DELETE] /product/:id

First, we create this product service to have CRUD functions for the product
services. As you can see, this ProductService has deleteProduct,
updateProduct, addProduct, getProductById, and getAllProducts. We will use
these services behind our Next.js API.

```
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(_ => _.id === id);
        if (result.length > 0) {
            return result[0];
        }
        return undefined;
    }

    addProduct(product: Product) {
        let maxId = Math.max(...this.products.map((x) => 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(_ => _.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(_ => _.id === id);
        if (!index) {
            return undefined;
        }

        this.products.splice(index, 1);

        return this.products;
    }
}

export default ProductService;
```

## Create API

First, we'll create an `index.ts` file under the api/product
folder. This file will handle HTTP GET, which returns all the products, and
POST, which adds a new product to the existing product service.

```
export default function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {

  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));
      ;
  }
}
```

Next, we'll create `[id].ts` to handle the dynamic Next.js API.
This file will handle our update, delete, and find-by-product-id APIs.

```
export default function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {

  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));
      ;
  }
}
```

## Verify the API

At this point, if you run the following URL, you should be able to see the API
response.

![Responsive image](https://d1p0mp3f1fx0hz.cloudfront.net/upload/2022/1/r1GHg1jCLEK7zeTJ3rSjZ3-153mzc3nb9520220110233250/750-153mzc3nb9520220110233250.png)

## Add Swagger JavaScript Comment

This is actually an important part of using Swagger UI with Next.js. You write
the Swagger documentation based on the Swagger API specification's YAML format.
Later, swagger-jsdoc will read this and generate the swagger.json file for the
UI to use.

Add this comment to the /api/product's index.ts file.

```
/**
 * @swagger
 * /api/product:
 *   get:
 *     tags:
 *          - Products
 *     description: Get all Product
 *     responses:
 *       200:
 *         description: Success
 */
```

## Add Swagger to Next.js

Now, since the API is ready, we can start setting up Swagger in Next.js.
First, I would like to show the Swagger UI when a user navigates to /swagger.
So, under the pages folder, create a swagger.tsx file.

When you navigate to **/swagger**, Next.js will render the
following page. The page itself uses the `swagger-ui-react` package.
It depends on the swagger.json file, which we'll create later.

Also, you can see that we import `swagger-ui.css` from the
`swagger-ui-react` library. If you have a custom CSS style, you can
import your style as well.

```
import { NextPage } from "next";
import SwaggerUI from "swagger-ui-react";
import "swagger-ui-react/swagger-ui.css";

const Home: NextPage = () => {
  return hi;
};
export default Home;
```

### Create swagger.json as Part of the Build Command

The following command will run the swagger-jsdoc task, which creates the
Swagger API specification based on the JavaScript documentation comments. The
Swagger UI will then use this JSON file to build the UI. As you can see, once
the swagger.json file is created, we move it to the public folder.

```
"scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "swagger": "swagger-jsdoc -d swaggerConfig.js && mv swagger.json ./public"
  },
```

## That Should Be All

After the above setup — writing APIs, adding API documentation comments, and
setting up Swagger in Next.js — you should be able to see the following
Swagger API documentation page. Now you can continue to add your APIs, add
the documentation comments for each API, and you'll have a centralized API
document to see all the APIs you have created.

![Responsive image](https://d1p0mp3f1fx0hz.cloudfront.net/upload/2022/1/uHgCecU8xgtU8Vz3cZfDzd-1p6ervh7ij520220110234502/750-1p6ervh7ij520220110234502.png)

## Conclusion

Swagger / OpenAPI is a popular and easy way to set up API documentation. With
API documentation, you can easily review all documents, run the API, check the
API specification for request or response objects, and test the API.

All the code mentioned here can be checked at
Github.


This blog walks through how to use Swagger / OpenAPI to add API documentation to Next.js, a Node.js framework. It covers how to create APIs in Next.js and add API documentation with Swagger using swagger-jsdoc and swagger-ui-react.

How to Setup Swagger with Next.js


## Table of Contents

1. [Introduction](#introduction)
2. [Setup Express.js](#setup-expressjs)
3. [Setup Express.js Server](#setup-expressjs-server)
4. [Create API at Express.js](#create-api-at-expressjs)
5. [Verify the API](#verify-the-api)
6. [Add Swagger UI Document](#add-swagger-ui-document)
7. [Adding Swagger Comment as YAML File](#adding-swagger-comment-as-yaml-file)
8. [Conclusion](#conclusion)

## Introduction

This blog walks through how to use Swagger / OpenAPI to add API documentation
to Express.js, a Node.js framework. It covers how to create APIs in Express.js
and add API documentation with Swagger using the OpenAPI 3.0 specification.

This blog mainly covers the following steps:

1. Create APIs with Express.js

2. Set up Swagger documentation with OpenAPI 3.0

## Setup Express.js

Here, we'll set up Express.js with the list of dependency packages needed for
this blog.

```
npm init -y
npm install --save express swagger-jsdoc swagger-ui-express
npm install --save-dev nodemon
```

After running the above commands, you should see a `package.json` file
created. It should look something close to this.

```
{
  "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"
  }
}
```

Let's take a look at these commands. First, run this to create a
`package.json` file with default settings.

```
npm init -y
```

Here, we'll install the list of packages: Express for the Node.js web server
(we'll create APIs later as well), and `swagger-jsdoc` and
`swagger-ui-express` for setting up Swagger documentation.

```
npm install --save express swagger-jsdoc swagger-ui-express
```

Lastly, install `nodemon` to reload server-side modules after you
make any changes.

```
npm install --save-dev nodemon
```

## Setup Express.js Server

Create an `index.js` file in the same directory as your
package.json file and add the following code. Once you run the code, it will
start the server on port 3106.

```
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);
```

## Create API at Express.js

In this section, we create a file called `product.js` and add the
following APIs. We create a temporary object to hold a list of products for
demo purposes. You can list all products, get by id, update, or delete by id.

- get all product list - [GET] /product

- get product by id - [GET] /product/:id

- create product - [POST] /product

- update product by id - [PUT] /product/:id

- delete product by id - [DELETE] /product/:id

```
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) => {
    res.json(products);
});

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

router.post('/', (req, res) => {

    if (req.body.name && req.body.price) {

        let maxId = Math.max(...products.map((x) => 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) => {

    if (req.body.name && req.body.price && req.params.id) {

        let result = products.find(_ => _.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) => {
    let index = products.findIndex(_ => _.id == req.params.id);
    if (index === null) {
        badRequest(res);
    }

    products.splice(index, 1);
    res.json(products);
})
```

## Verify the API

At this point, if you run the following URL, you should be able to see the API
response.

![Responsive image](https://d1p0mp3f1fx0hz.cloudfront.net/upload/2021/12/7iMzyJjBYpSwn9pJnRog5r-w7pfjpp4bl20211216002746/750-w7pfjpp4bl20211216002746.png)

## Add Swagger UI Document

### Create Swagger Option File

We'll use Swagger's OpenAPI version 3.0. The following is a simple setup for
the main Swagger configuration. Let's create a file called swaggerConfig.js
and add the following 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;
```

### Add Swagger Configuration

Here, we'll import two modules: `swagger-ui-express` and
`swagger-jsdoc`. Import the Swagger config we created earlier and
add the Swagger configuration.

```
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);
 });
```

## Adding Swagger Comment as YAML File

Now, we need the last step. If you navigate to /swagger now, you won't see
the Swagger UI document yet. So let's add comments to each API we created
earlier. The following code adds the documentation for the API that gets all
products. After you add the following JSDoc comment and navigate to /swagger,
you should see the Swagger UI page as below.

```
/**
 * @swagger
 * /product:
 *   get:
 *     tags:
 *          - Products
 *     description: Get all Product
 *     responses:
 *       200:
 *         description: Success
 */
router.get('/', (req, res) => {
    res.json(products);
});
```

Cool, right!? Now, you can use this Swagger UI to view the details of each
API and execute the API from this UI as well.

![Responsive image](https://d1p0mp3f1fx0hz.cloudfront.net/upload/2021/12/9u2jZF82Yp11W74X7Gwznm-n27s0dskrh20211216004311/750-n27s0dskrh20211216004311.png)

Now, the following is the code with the Swagger comments for all the APIs.

```
**
 * @swagger
 * /product:
 *   get:
 *     tags:
 *          - Products
 *     description: Get all Product
 *     responses:
 *       200:
 *         description: Success
 */
router.get('/', (req, res) => {
    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) => {
    let result = products.filter(_ => _.id == req.params.id);
    if (result.length > 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) => {


    if (req.body.name && req.body.price) {

        let maxId = Math.max(...products.map((x) => 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) => {

    if (req.body.name && req.body.price && req.params.id) {

        let result = products.find(_ => _.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) => {
    let index = products.findIndex(_ => _.id == req.params.id);
    if (index === null) {
        badRequest(res);
    }

    products.splice(index, 1);
    res.json(products);
})
```

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
[here](https://swagger.io/specification/).

## Conclusion

Swagger / OpenAPI is a popular and easy way to set up API documentation. 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 that you have to use YAML comments for each API. That process is done
manually and could be error-prone. Maybe there's something better to use for
Express.js — I'll continue and write about it once I find out.

All the code mentioned here can be reviewed at
Github.


This blog walks through how to use Swagger / OpenAPI to add API documentation to Express.js, a Node.js framework. It covers how to create APIs in Express.js and add API documentation with Swagger using the OpenAPI 3.0 specification.

How to Setup Swagger OpenAPI with Express.js


## Table of Contents

1. [Introduction](#introduction)
2. [Setup Nest.js Project](#setup-nestjs-project)
3. [Setup Swagger UI in Nest.js](#setup-swagger-ui-in-nestjs)
4. [Create APIs](#create-apis)
5. [Run the App](#run-the-app)
6. [Conclusion](#conclusion)

## Introduction

This blog is about how to set up Swagger / OpenAPI with Nest.js, a progressive
Node.js framework. It covers how to define a few sample APIs and how to enable
Swagger UI in Nest.js.

![Responsive image](https://d1p0mp3f1fx0hz.cloudfront.net/upload/2021/12/32CDbRcaEajQgwXggRxgLz-3cuyrtgzyt20211205162214/750-3cuyrtgzyt20211205162214.png)

## Setup Nest.js Project

First, we'll set up the Nest.js project with TypeScript. Run the following
command to clone the TypeScript template with Nest.js without the history.

```
degit https://github.com/nestjs/typescript-starter.git swagger-nestjs
```

Install dependency packages for setting up Swagger in Nest.js.

```
npm install --save @nestjs/swagger swagger-ui-express
```

## Setup Swagger UI in Nest.js

Here, we'll add code to set up Swagger UI in Nest.js's main.ts, including the
title and description of this API.

```
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();
```

## Create APIs

Here, we'll create some sample code for the example API and add a few
decorators to the API so they will display in the Swagger UI.

```
@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);
  }
}
```

For instance, the following decorators for the API indicate the list of HTTP
status codes that will be returned by this API. An endpoint consuming the API
can handle the HTTP response status code accordingly.

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

## Run the App

Now, everything should be ready. The following commands will install all the
dependencies and start the Nest.js application.

```
npm install
npm run start
```

While the application is running, browse and navigate to
[http://localhost:3000/api](../api). You can see the documentation
of your APIs in the Swagger UI.

![Responsive image](https://d1p0mp3f1fx0hz.cloudfront.net/upload/2021/12/69JpPkAKBx8HATufVLbDNM-1ot209a3z6v20211205233226/750-1ot209a3z6v20211205233226.png)

## Conclusion

This is how you can set up Swagger UI for a Nest.js application. All the code
referenced here can be found
here.


This blog is about how to set up Swagger / OpenAPI with Nest.js, a progressive Node.js framework. It covers how to define a few sample APIs and how to enable Swagger UI in Nest.js.

How to Setup Swagger with Nest.js

## Table of Contents

1. [Introduction](#introduction)
2. [What's Swagger?](#whats-swagger)
3. [Use Azure API App Template with Swagger](#use-azure-api-app-template-with-swagger)
4. [Can I Use a Customized Stylesheet for Swagger?](#can-i-use-a-customized-stylesheet-for-swagger)
5. [Can I Add My Own JavaScript File to Swagger API Documents?](#can-i-add-my-own-javascript-file-to-swagger-api-documents)
6. [Can We Change the Entire HTML?](#now-we-know-we-can-change-javascript-css-can-we-change-the-entire-html)
7. [Add .NET XML Comment for Swagger's API Description](#add-net-xml-comment-for-swaggers-api-description)
8. [Conclusion](#conclusion)

## Introduction

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

## What's Swagger?

Swagger could provide richer documentation for your API, but that's not all — it
provides tools to design, test, and document 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, discoverability, and broader
developer support.

This blog will show how to use Swagger with an ASP.NET MVC API project and provide
a list of how-tos.

> With a Swagger-enabled API, you get interactive documentation, client SDK
> generation and discoverability.

```
Install-Package Swashbuckle
```

The following are a few resources related to Swagger.

- [swagger.io](http://swagger.io/)

- Swashbuckle

- swagger-codegen

- swagger-ui

- OpenAPI Specification

## Use Azure API App Template with Swagger

You can use Swagger with Visual Studio 2015, ASP.NET 4.5.2 Templates. Once you
use Visual Studio and create a web application using the Azure API App template, in
your solution you should see the following Swagger entry in the package file.

![](http://res.cloudinary.com/dmwrakaup/image/upload/v1458931625/vrtczaiykyxoxtecgloc.png)

You will find the NuGet library `Swashbuckle`, which is the .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.

![](https://d1p0mp3f1fx0hz.cloudfront.net/_dp4q0c174.png)

### SwaggerConfig, EnableSwaggerUi, and Basic Configuration

After installing Swashbuckle, you will see a SwaggerConfig under your
App_Start folder. This `SwaggerConfig` is the starting point to enable
Swagger. If you already have the following content, then your setup is
done. We should see the API documentation generated by Swagger.

```
[assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]

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

            GlobalConfiguration.Configuration

                .EnableSwagger(c =>
                    // {...
                    // this will enable swagger UI
                .EnableSwaggerUi(c =>
```

### Build the Solution and Check the URL

Navigate to `{yoururl}/swagger` or `{yoururl}/swagger/ui/index`.

You should be able to see the following Swagger UI documentation page. I
have two Web APIs, `TestController` and
`ValuesController`. As you can see, it contains a search feature
and you can try it out.

![](http://res.cloudinary.com/dmwrakaup/image/upload/v1458932570/vbbqw3dh7xbalqxmxlyd.png)

![](https://d1p0mp3f1fx0hz.cloudfront.net/_3cxww0sfn.png)

However, I also had the following questions when I first saw these pages
generated by Swagger.

- Can I change this API document's UI, including the logo and stylesheet?

- Can I add JavaScript to this?

- Can I change the URL instead of /swagger?

- Can I add my own page to this auto-generated page?

- Can I make certain Web APIs not show up?

- Can I turn the Swagger API documentation off in production, but keep it only in
  development?

I might not cover all these questions I have in mind, but I will give them a
try and list them here.

## Can I Use a Customized Stylesheet for Swagger?

Let's assume I want to change the following style, which changes the header
background color to `#704C8F`.

### 1. CSS File

```
.swagger-section #header {
    background-color: #704C8F;
    padding: 14px;
}
```

### 2. SwaggerConfig

```
.EnableSwaggerUi(c =>                   {
c.InjectStylesheet(Assembly.GetAssembly(typeof(WebApiApplication)), "WebApplication2.styles.swagger_test.css");
```

### 3. Global.asax

#### How the WebApiApplication Looks

The SwaggerConfig's InjectStyleSheet's first parameter needs to pass the
current application's assembly. The second parameter is a little tricky. The
filename `WebApplication2.styles.swagger_test.css` is
`Project Folder name`.`{folder name}` and the file name.

```
namespace WebApplication2
{
    public class WebApiApplication : System.Web.HttpApplication
    {
        protected void Application_Start()
        {
            AreaRegistration.RegisterAllAreas();
            GlobalConfiguration.Configure(WebApiConfig.Register);
            RouteConfig.RegisterRoutes(RouteTable.Routes);
        }
    }
}
```

#### 4. Styles File Location

Also, this is very important — you must set the file's Build Action to Embedded
Resource.

```

```

#### 5. After Steps 1–4, How the Page Looks

![](http://res.cloudinary.com/dmwrakaup/image/upload/v1458968917/vetiqfmu4mizsfyolm2h.png)

## Can I Add My Own JavaScript File to Swagger API Documents?

You are able to do it as follows. Assume you have a JavaScript file like this.

### 1. JavaScript

```
(function () {
    function init() {

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

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

    init();
})();
```

### 2. JavaScript File Location and Build Action Property

```

```

### 3. SwaggerConfig Class

Set the JavaScript path as a string type like the following.

```
var myAssembly = Assembly.GetAssembly(typeof(WebApiApplication));
   c.InjectJavaScript(myAssembly, "WebApplication2.js.swagger_test.js");
```

### 4. Done, Check the Page

When the page loads, 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?

![](http://res.cloudinary.com/dmwrakaup/image/upload/v1458969860/h3novy9llbwau4kearez.png)

## Now, We Know We Can Change JavaScript, CSS — Can We Change the Entire HTML?

Yes, and the main features will still work if you use Swagger's existing
JavaScript. The following is how we can do it.

### 1. HTML Files

This time I want to add two HTML files. After creating these HTML files, you also have to
change the Build Action to Embedded Resource again.

![](http://res.cloudinary.com/dmwrakaup/image/upload/v1458971711/evgs4ci6wclqwpqpirxg.png)

swagger_test.html

```
Bomm!!!!
```

OtherVersion.html

```
<!DOCTYPE html>



    Swagger UI My Own Version






















    
    
    
    


    $(function () {
      var url = window.location.search.match(/url=([^&]+)/);
      if (url && url.length > 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" && 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 && 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);
        }
      }
  });



    Damn, I love this! Swagger!





```

### 2. SwaggerConfig for HTML

```
c.CustomAsset("swagger_test", myAssembly, "WebApplication2.html.swagger_test.html");
                        c.CustomAsset("OtherVersion", myAssembly, "WebApplication2.html.OtherVersion.html");
```

### 3. Check the Browser

Now, you're going to ask: what's the URL? I didn't figure it out at
first, but it looks like Swagger uses the file name as the URL. Since
their default page is /swagger/ui/index, my new files' URLs will be
`/swagger/ui/OtherVersion` and
`/swagger/ui/swagger_test`.

The following is one of my new pages, OtherVersion. Isn't this great? As a
developer, when you use another UI framework and you can replace CSS, JavaScript,
and HTML while keeping the original logic, that's just fantastic.

![](http://res.cloudinary.com/dmwrakaup/image/upload/v1458972150/uiblm9hoxxitxz1fgxls.png)

## Add .NET XML Comment for Swagger's API Description

ASP.NET WebAPI's default API helper documentation also looks for the DLL's XML comments
for descriptions. We can do that in Swagger too.

### 1. Project Property

The first thing you need to do is go to the project that contains the API
controller and check the XML documentation file. When building the solution,
Visual Studio will update the XML with comments you add to the class. Also,
Swagger will later read the XML comments as descriptions for the API.

![](http://res.cloudinary.com/dmwrakaup/image/upload/v1459030325/o170ozq0mak76k8hfoqi.png)

### 2. SwaggerConfig Setting

The next important thing is that Swagger has not registered the API XML. You can
add it as follows.

```
c.IncludeXmlComments(string.Format(@"{0}\bin\APIDemo.XML", System.AppDomain.CurrentDomain.BaseDirectory));
```

The following are examples of the WebAPI controller and the API Model class's XML
documentation.

```
///
    /// my product
    ///
    public class Product
    {
        ///
        /// product id
        ///
        public Guid GuidId { get; set; }
        ///
        /// product Id
        ///
        public int ProductId { get; set; }
        ///
        /// product name
        ///
        public string ProductName { get; set; }
        ///
        /// product price
        ///
        public decimal Price { get; set; }
        ///
        /// product unit
        ///
        public int Unit { get; set; }
```

```
///
    /// ProductController API
    ///
    public class ProductController : ApiController
    {
        ///
        /// products data
        ///
        public static ListProducts
        {
            get
            {
                return new List
                {
                    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)
                };
            }
        }

        ///
        ///  get values for products
        ///
        ///
        public IEnumerable Get()
        {
            return Products;
        }
```

### 3. Done! Let's Browse the API Documentation

Now we're done. After building the solution, you should see your XML comments
added to the C# class on the Swagger API documentation page.

![](https://d1p0mp3f1fx0hz.cloudfront.net/_iw664rs80.png)

## Conclusion

Swagger with ASP.NET MVC provides very powerful API documentation and it
is very flexible. You can customize the CSS, JavaScript, and HTML while retaining the core Swagger functionality.

Check the
Code
mentioned in this blog.

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

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