Swagger Show Decimal as 0.00 Instead of 0: A Comprehensive Guide

Are you tired of seeing those unsightly zeros in your Swagger API documentation? Do you want to display decimal values with precision and accuracy? Look no further! In this article, we’ll show you how to configure Swagger to display decimal values as 0.00 instead of 0.

Why Does Swagger Display Decimal Values as 0?

By default, Swagger uses the Jackson library to serialize and deserialize JSON data. Jackson’s default behavior is to remove trailing zeros from decimal values, resulting in 0 instead of 0.00. This can be problematic, especially when working with financial or scientific applications where precision is crucial.

The Solution: Using Swagger’s NumberFormat Annotation

Luckily, Swagger provides a simple solution to this problem: the `@NumberFormat` annotation. This annotation allows you to specify the format of numeric values, including decimal places.

.schema(
  type: 'number',
  format: 'decimal',
  example: 0.00
)

In the above example, we’ve added the `format` property to the schema definition and set it to `decimal`. This tells Swagger to display decimal values with precision.

Configuring NumberFormat at the Global Level

If you want to apply the `@NumberFormat` annotation globally, you can do so by configuring the `swagger` object in your API definition.

swagger: '2.0'
info:
  title: My API
  description: My API description
  version: 1.0.0
host: localhost:8080
basePath: /api
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
paths:
  /users:
    get:
      summary: Get users
      responses:
        200:
          description: Users list
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
      balance:
        type: number
        format: decimal
        example: 0.00

In the above example, we’ve added the `format` property to the `balance` property of the `User` definition. This will apply the `decimal` format to all instances of the `balance` property throughout the API.

Using Swagger’s NumberFormat with Other Data Types

The `@NumberFormat` annotation is not limited to decimal values. You can use it with other numeric data types, such as integers and floats, to specify the format of the value.

Data Type	Format	Example
Integer	integer	12345
Float	float	123.45
Decimal	decimal	0.00
Long	long	1234567890

In the above table, we’ve listed some common numeric data types and their corresponding formats. You can use these formats with the `@NumberFormat` annotation to specify the format of your numeric values.

Best Practices for Using Swagger’s NumberFormat

Here are some best practices to keep in mind when using Swagger’s `@NumberFormat` annotation:

1. Be consistent: Use the same format throughout your API to maintain consistency and readability.
2. Use meaningful examples: Provide meaningful examples for each numeric property to help users understand the format and range of values.
3. Specify the format explicitly: Avoid relying on Swagger’s default formatting, and instead, specify the format explicitly using the `@NumberFormat` annotation.
4. Test your API: Test your API thoroughly to ensure that the `@NumberFormat` annotation is working correctly and displaying the desired format.

Conclusion

In this article, we’ve shown you how to configure Swagger to display decimal values as 0.00 instead of 0 using the `@NumberFormat` annotation. We’ve also covered some best practices for using this annotation effectively. By following these guidelines, you can ensure that your API documentation is accurate, consistent, and easy to read.

Remember, Swagger is a powerful tool that provides a lot of customization options. Take the time to explore its features and configuration options to create high-quality API documentation that meets your needs.

Additional Resources

For more information on Swagger and its configuration options, check out the following resources:

• Swagger 2.0 Specification
• Swagger Annotations
• Swagger Tutorial

We hope you found this article helpful! If you have any questions or need further assistance, please don’t hesitate to ask.

Frequently Asked Question

Get the scoop on how to show decimals in Swagger with our top 5 FAQs!