MIME Types

An API can accept and return data in different formats, the most common being JSON and XML. You can use the consumes and produces keywords to specify the MIME types understood by your API. The value of consumes and produces is an array of MIME types. Global MIME types can be defined on the root level of an API specification and are inherited by all API operations. Here the API uses JSON and XML:

1
consumes:
2
  - application/json
3
  - application/xml
4
produces:
5
  - application/json
6
  - application/xml

Note that consumes only affects operations with a request body, such as POST, PUT and PATCH. It is ignored for bodiless operations like GET. When used on the operation level, consumes and produces override (not extend) the global definitions. In the following example, the GET /logo operation redefines the produces array to return an image:

1
paths:
2
  /logo:
3
    get:
4
      summary: Returns the logo image
5
      produces:
6
        - image/png
7
        - image/gif
8
        - image/jpeg
9
      responses:
10
        200:
11
          description: OK
12
          schema:
13
            type: file

MIME types listed in consumes and produces should be compliant with RFC 6838. For example, you can use standard MIME types such as:

1
application/json
2
application/xml
3
application/x-www-form-urlencoded
4
multipart/form-data
5
text/plain; charset=utf-8
6
text/html
7
application/pdf
8
image/png

as well as vendor-specific MIME types (indicated by vnd.):

1
application/vnd.mycompany.myapp.v2+json
2
application/vnd.ms-excel
3
application/vnd.openstreetmap.data+xml
4
application/vnd.github-issue.text+json
5
application/vnd.github.v3.diff
6
image/vnd.djvu

Did not find what you were looking for? Ask the community
Found a mistake? Let us know