Documenting POST endpoint using base64 encoding

Hi, I am trying to document an enpoint that encodes 2 variables. Is it possible to use base64? I know how to do it under security definitions, but we need to have it fully documented as a standalone POST/.

POST: /v1/url HTTP/1.1
Host: host.api
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(*CLIENT_ID_VALUE* + “:” + *CLIENT_SECRET_VALUE*)

grant_type=client_credentials

Thanks!

[Yaima]

Thanks for the detailed walkthrough @hkosova. My swagger doc has security and securityDefinitions defined. I was trying to document the /post for the token request outside the pop-up window, in details. For now, I ended up removing the Try Out button from it, to still keep the endpoint documentation visible but hiding any working logic around it, so if someone is exploring the API docs and they don’t want to try them, they can still read the /post logic outside the Authorize pop-up.

[hkosova]

@Yaima In this scenario, client ID and client secret cannot (and should not) be described as parameters. Authorization: Basic base64(value1:value2) request header is handled by security definitions instead. Here’s a more detailed example:

paths:
  /v1/oauth/token:
    post:
      summary: Get access token
      description: >-
        Token request must be authenticated using Basic authentication, with the client ID
        as the username and client secret as the password. That is, the token request must
        include the following header:

            Authorization: Basic base64(client_id:client_secret)

        **When testing the API call in Swagger UI, click the lock icon to specify
        the client ID and secret for authentication.**
      security:
        - TokenRequestBasicAuth: []
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - in: formData
          name: grant_type
          required: true
          type: string
          enum: [client_credentials]
      responses:
        200:
          description: OK

securityDefinitions:
  TokenRequestBasicAuth:
    type: basic
    description: >-
      Authentication for the OAuth 2 token request (`/v1/oauth/token`).
      Use client ID as the username and client secret as the password.

To test the API call in Swagger UI, click the authorize button and enter the client ID and secret in the authorization dialog. They send the request. The request will be sent with the properly encoded Authorization header. The security definition (TokenRequestBasicAuth) is responsible for constructing the Authorization header.

This is how it can be done using standard OpenAPI syntax and vanilla Swagger UI.

If you mean you want to display client_id and client_secret in the Parameters list instead (along with grant_type), then you’ll need to implement custom logic in your Swagger UI. For example, you could use extension properties (x-...) to describe the client ID and secret, like so:

parameters:
  - in: formData
    name: grant_type
    required: true
    type: string
    enum: [client_credentials]
x-parameters:  # <---------
  - client_id
  - client_secret

and add code that would display them and then build the Authorization header based on their values. @shockey might have more ideas about how such customization could be implemented.