feat: openapi schema

[titpetric]

As a user I'd like a swagger schema for the known APIs to be provided on /swagger.yml (or appropriate path) by the service itself.

• does such a schema exist?
• is there already a way to request it?

[mccutchen]

does such a schema exist?

Not for go-httpbin specifically. We could consider starting from the official https://httpbin.org/spec.json swagger schema, but it's a bit outdated (using an older Swagger version rather than a newer OpenAPI version) and would need to be at least lightly adapted to go-httpbin's slightly different set of endpoints.

(It also does not specify response types, but maybe that's okay in this context!)

is there already a way to request it?

Nope, would you like to take a pass at adding such a thing?

[julian-alarcon]

For an initial effort, this is the converted Swagger to openAPI 3.0.x

OpenAPI 3.0.x for go-httpbin

openapi: 3.0.1
info:
  title: httpbin.org
  description: "A golang port of the venerable httpbin.org HTTP request & response testing service."
  contact:
    url: https://github.com/mccutchen/go-httpbin
  version: 0.0.1
servers:
- url: https://httpbingo.org/
tags:
- name: HTTP Methods
  description: Testing different HTTP verbs
- name: Auth
  description: Auth methods
- name: Status codes
  description: Generates responses with given status code
- name: Request inspection
  description: Inspect the request data
- name: Response inspection
  description: Inspect the response data like caching and headers
- name: Response formats
  description: Returns responses in different data formats
- name: Dynamic data
  description: Generates random and dynamic data
- name: Cookies
  description: "Creates, reads and deletes Cookies"
- name: Images
  description: Returns different image formats
- name: Redirects
  description: Returns different redirect responses
- name: Anything
  description: Returns anything that is passed to request
paths:
  /absolute-redirect/{n}:
    get:
      tags:
      - Redirects
      summary: Absolutely 302 Redirects n times.
      parameters:
      - name: "n"
        in: path
        required: true
        schema: {}
      responses:
        "302":
          description: A redirection.
          content: {}
  /anything:
    get:
      tags:
      - Anything
      summary: Returns anything passed in request data.
      responses:
        "200":
          description: Anything passed in request
          content: {}
    put:
      tags:
      - Anything
      summary: Returns anything passed in request data.
      responses:
        "200":
          description: Anything passed in request
          content: {}
    post:
      tags:
      - Anything
      summary: Returns anything passed in request data.
      responses:
        "200":
          description: Anything passed in request
          content: {}
    delete:
      tags:
      - Anything
      summary: Returns anything passed in request data.
      responses:
        "200":
          description: Anything passed in request
          content: {}
    patch:
      tags:
      - Anything
      summary: Returns anything passed in request data.
      responses:
        "200":
          description: Anything passed in request
          content: {}
  /anything/{anything}:
    get:
      tags:
      - Anything
      summary: Returns anything passed in request data.
      responses:
        "200":
          description: Anything passed in request
          content: {}
    put:
      tags:
      - Anything
      summary: Returns anything passed in request data.
      responses:
        "200":
          description: Anything passed in request
          content: {}
    post:
      tags:
      - Anything
      summary: Returns anything passed in request data.
      responses:
        "200":
          description: Anything passed in request
          content: {}
    delete:
      tags:
      - Anything
      summary: Returns anything passed in request data.
      responses:
        "200":
          description: Anything passed in request
          content: {}
    patch:
      tags:
      - Anything
      summary: Returns anything passed in request data.
      responses:
        "200":
          description: Anything passed in request
          content: {}
  /base64/{value}:
    get:
      tags:
      - Dynamic data
      summary: Decodes base64url-encoded string.
      parameters:
      - name: value
        in: path
        required: true
        schema:
          type: string
          default: SFRUUEJJTiBpcyBhd2Vzb21l
      responses:
        "200":
          description: Decoded base64 content.
          content: {}
  /basic-auth/{user}/{passwd}:
    get:
      tags:
      - Auth
      summary: Prompts the user for authorization using HTTP Basic Auth.
      parameters:
      - name: user
        in: path
        required: true
        schema:
          type: string
      - name: passwd
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Sucessful authentication.
          content: {}
        "401":
          description: Unsuccessful authentication.
          content: {}
  /bearer:
    get:
      tags:
      - Auth
      summary: Prompts the user for authorization using bearer authentication.
      parameters:
      - name: Authorization
        in: header
        schema: {}
      responses:
        "200":
          description: Sucessful authentication.
          content: {}
        "401":
          description: Unsuccessful authentication.
          content: {}
  /brotli:
    get:
      tags:
      - Response formats
      summary: Returns Brotli-encoded data.
      responses:
        "200":
          description: Brotli-encoded data.
          content: {}
  /bytes/{n}:
    get:
      tags:
      - Dynamic data
      summary: Returns n random bytes generated with given seed
      parameters:
      - name: "n"
        in: path
        required: true
        schema: {}
      responses:
        "200":
          description: Bytes.
          content: {}
  /cache:
    get:
      tags:
      - Response inspection
      summary: Returns a 304 if an If-Modified-Since header or If-None-Match is present.
        Returns the same as a GET otherwise.
      parameters:
      - name: If-Modified-Since
        in: header
        schema: {}
      - name: If-None-Match
        in: header
        schema: {}
      responses:
        "200":
          description: Cached response
          content: {}
        "304":
          description: Modified
          content: {}
  /cache/{value}:
    get:
      tags:
      - Response inspection
      summary: Sets a Cache-Control header for n seconds.
      parameters:
      - name: value
        in: path
        required: true
        schema:
          type: integer
      responses:
        "200":
          description: Cache control set
          content: {}
  /cookies:
    get:
      tags:
      - Cookies
      summary: Returns cookie data.
      responses:
        "200":
          description: Set cookies.
          content: {}
  /cookies/delete:
    get:
      tags:
      - Cookies
      summary: Deletes cookie(s) as provided by the query string and redirects to
        cookie list.
      parameters:
      - name: freeform
        in: query
        allowEmptyValue: true
        schema: {}
      responses:
        "200":
          description: Redirect to cookie list
          content: {}
  /cookies/set:
    get:
      tags:
      - Cookies
      summary: Sets cookie(s) as provided by the query string and redirects to cookie
        list.
      parameters:
      - name: freeform
        in: query
        allowEmptyValue: true
        schema: {}
      responses:
        "200":
          description: Redirect to cookie list
          content: {}
  /cookies/set/{name}/{value}:
    get:
      tags:
      - Cookies
      summary: Sets a cookie and redirects to cookie list.
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      - name: value
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Set cookies and redirects to cookie list.
          content: {}
  /deflate:
    get:
      tags:
      - Response formats
      summary: Returns Deflate-encoded data.
      responses:
        "200":
          description: Defalte-encoded data.
          content: {}
  /delay/{delay}:
    get:
      tags:
      - Dynamic data
      summary: Returns a delayed response (max of 10 seconds).
      parameters:
      - name: delay
        in: path
        required: true
        schema: {}
      responses:
        "200":
          description: A delayed response.
          content: {}
    put:
      tags:
      - Dynamic data
      summary: Returns a delayed response (max of 10 seconds).
      parameters:
      - name: delay
        in: path
        required: true
        schema: {}
      responses:
        "200":
          description: A delayed response.
          content: {}
    post:
      tags:
      - Dynamic data
      summary: Returns a delayed response (max of 10 seconds).
      parameters:
      - name: delay
        in: path
        required: true
        schema: {}
      responses:
        "200":
          description: A delayed response.
          content: {}
    delete:
      tags:
      - Dynamic data
      summary: Returns a delayed response (max of 10 seconds).
      parameters:
      - name: delay
        in: path
        required: true
        schema: {}
      responses:
        "200":
          description: A delayed response.
          content: {}
    patch:
      tags:
      - Dynamic data
      summary: Returns a delayed response (max of 10 seconds).
      parameters:
      - name: delay
        in: path
        required: true
        schema: {}
      responses:
        "200":
          description: A delayed response.
          content: {}
  /delete:
    delete:
      tags:
      - HTTP Methods
      summary: The request's DELETE parameters.
      responses:
        "200":
          description: The request's DELETE parameters.
          content: {}
  /deny:
    get:
      tags:
      - Response formats
      summary: Returns page denied by robots.txt rules.
      responses:
        "200":
          description: Denied message
          content: {}
  /digest-auth/{qop}/{user}/{passwd}:
    get:
      tags:
      - Auth
      summary: Prompts the user for authorization using Digest Auth.
      parameters:
      - name: qop
        in: path
        description: auth or auth-int
        required: true
        schema:
          type: string
      - name: user
        in: path
        required: true
        schema:
          type: string
      - name: passwd
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Sucessful authentication.
          content: {}
        "401":
          description: Unsuccessful authentication.
          content: {}
  /digest-auth/{qop}/{user}/{passwd}/{algorithm}:
    get:
      tags:
      - Auth
      summary: Prompts the user for authorization using Digest Auth + Algorithm.
      parameters:
      - name: qop
        in: path
        description: auth or auth-int
        required: true
        schema:
          type: string
      - name: user
        in: path
        required: true
        schema:
          type: string
      - name: passwd
        in: path
        required: true
        schema:
          type: string
      - name: algorithm
        in: path
        description: "MD5, SHA-256, SHA-512"
        required: true
        schema:
          type: string
          default: MD5
      responses:
        "200":
          description: Sucessful authentication.
          content: {}
        "401":
          description: Unsuccessful authentication.
          content: {}
  /digest-auth/{qop}/{user}/{passwd}/{algorithm}/{stale_after}:
    get:
      tags:
      - Auth
      summary: Prompts the user for authorization using Digest Auth + Algorithm.
      description: |
        allow settings the stale_after argument.
      parameters:
      - name: qop
        in: path
        description: auth or auth-int
        required: true
        schema:
          type: string
      - name: user
        in: path
        required: true
        schema:
          type: string
      - name: passwd
        in: path
        required: true
        schema:
          type: string
      - name: algorithm
        in: path
        description: "MD5, SHA-256, SHA-512"
        required: true
        schema:
          type: string
          default: MD5
      - name: stale_after
        in: path
        required: true
        schema:
          type: string
          default: never
      responses:
        "200":
          description: Sucessful authentication.
          content: {}
        "401":
          description: Unsuccessful authentication.
          content: {}
  /drip:
    get:
      tags:
      - Dynamic data
      summary: Drips data over a duration after an optional initial delay.
      parameters:
      - name: duration
        in: query
        description: The amount of time (in seconds) over which to drip each byte
        schema:
          type: number
          default: 2.0
      - name: numbytes
        in: query
        description: The number of bytes to respond with
        schema:
          type: integer
          default: 10
      - name: code
        in: query
        description: The response code that will be returned
        schema:
          type: integer
          default: 200
      - name: delay
        in: query
        description: The amount of time (in seconds) to delay before responding
        schema:
          type: number
          default: 2.0
      responses:
        "200":
          description: A dripped response.
          content: {}
  /encoding/utf8:
    get:
      tags:
      - Response formats
      summary: Returns a UTF-8 encoded body.
      responses:
        "200":
          description: Encoded UTF-8 content.
          content: {}
  /etag/{etag}:
    get:
      tags:
      - Response inspection
      summary: Assumes the resource has the given etag and responds to If-None-Match
        and If-Match headers appropriately.
      parameters:
      - name: If-None-Match
        in: header
        schema: {}
      - name: If-Match
        in: header
        schema: {}
      responses:
        "200":
          description: Normal response
          content: {}
        "412":
          description: match
          content: {}
  /get:
    get:
      tags:
      - HTTP Methods
      summary: The request's query parameters.
      responses:
        "200":
          description: The request's query parameters.
          content: {}
  /gzip:
    get:
      tags:
      - Response formats
      summary: Returns GZip-encoded data.
      responses:
        "200":
          description: GZip-encoded data.
          content: {}
  /headers:
    get:
      tags:
      - Request inspection
      summary: Return the incoming request's HTTP headers.
      responses:
        "200":
          description: The request's headers.
          content: {}
  /hidden-basic-auth/{user}/{passwd}:
    get:
      tags:
      - Auth
      summary: Prompts the user for authorization using HTTP Basic Auth.
      parameters:
      - name: user
        in: path
        required: true
        schema:
          type: string
      - name: passwd
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Sucessful authentication.
          content: {}
        "404":
          description: Unsuccessful authentication.
          content: {}
  /html:
    get:
      tags:
      - Response formats
      summary: Returns a simple HTML document.
      responses:
        "200":
          description: An HTML page.
          content: {}
  /image:
    get:
      tags:
      - Images
      summary: Returns a simple image of the type suggest by the Accept header.
      responses:
        "200":
          description: An image.
          content: {}
  /image/jpeg:
    get:
      tags:
      - Images
      summary: Returns a simple JPEG image.
      responses:
        "200":
          description: A JPEG image.
          content: {}
  /image/png:
    get:
      tags:
      - Images
      summary: Returns a simple PNG image.
      responses:
        "200":
          description: A PNG image.
          content: {}
  /image/svg:
    get:
      tags:
      - Images
      summary: Returns a simple SVG image.
      responses:
        "200":
          description: An SVG image.
          content: {}
  /image/webp:
    get:
      tags:
      - Images
      summary: Returns a simple WEBP image.
      responses:
        "200":
          description: A WEBP image.
          content: {}
  /ip:
    get:
      tags:
      - Request inspection
      summary: Returns the requester's IP Address.
      responses:
        "200":
          description: The Requester's IP Address.
          content: {}
  /json:
    get:
      tags:
      - Response formats
      summary: Returns a simple JSON document.
      responses:
        "200":
          description: An JSON document.
          content: {}
  /links/{n}/{offset}:
    get:
      tags:
      - Dynamic data
      summary: Generate a page containing n links to other pages which do the same.
      parameters:
      - name: "n"
        in: path
        required: true
        schema: {}
      - name: offset
        in: path
        required: true
        schema: {}
      responses:
        "200":
          description: HTML links.
          content: {}
  /patch:
    patch:
      tags:
      - HTTP Methods
      summary: The request's PATCH parameters.
      responses:
        "200":
          description: The request's PATCH parameters.
          content: {}
  /post:
    post:
      tags:
      - HTTP Methods
      summary: The request's POST parameters.
      responses:
        "200":
          description: The request's POST parameters.
          content: {}
  /put:
    put:
      tags:
      - HTTP Methods
      summary: The request's PUT parameters.
      responses:
        "200":
          description: The request's PUT parameters.
          content: {}
  /range/{numbytes}:
    get:
      tags:
      - Dynamic data
      summary: "Streams n random bytes generated with given seed, at given chunk size\
        \ per packet."
      parameters:
      - name: numbytes
        in: path
        required: true
        schema: {}
      responses:
        "200":
          description: Bytes.
          content: {}
  /redirect-to:
    get:
      tags:
      - Redirects
      summary: 302/3XX Redirects to the given URL.
      parameters:
      - name: url
        in: query
        required: true
        schema:
          type: string
      - name: status_code
        in: query
        schema: {}
      responses:
        "302":
          description: A redirection.
          content: {}
    put:
      tags:
      - Redirects
      summary: 302/3XX Redirects to the given URL.
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - url
              type: object
              properties:
                url:
                  type: string
                status_code: {}
        required: true
      responses:
        "302":
          description: A redirection.
          content: {}
    post:
      tags:
      - Redirects
      summary: 302/3XX Redirects to the given URL.
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - url
              type: object
              properties:
                url:
                  type: string
                status_code: {}
        required: true
      responses:
        "302":
          description: A redirection.
          content: {}
    delete:
      tags:
      - Redirects
      summary: 302/3XX Redirects to the given URL.
      responses:
        "302":
          description: A redirection.
          content: {}
    patch:
      tags:
      - Redirects
      summary: 302/3XX Redirects to the given URL.
      responses:
        "302":
          description: A redirection.
          content: {}
  /redirect/{n}:
    get:
      tags:
      - Redirects
      summary: 302 Redirects n times.
      parameters:
      - name: "n"
        in: path
        required: true
        schema: {}
      responses:
        "302":
          description: A redirection.
          content: {}
  /relative-redirect/{n}:
    get:
      tags:
      - Redirects
      summary: Relatively 302 Redirects n times.
      parameters:
      - name: "n"
        in: path
        required: true
        schema: {}
      responses:
        "302":
          description: A redirection.
          content: {}
  /response-headers:
    get:
      tags:
      - Response inspection
      summary: Returns a set of response headers from the query string.
      parameters:
      - name: freeform
        in: query
        allowEmptyValue: true
        schema: {}
      responses:
        "200":
          description: Response headers
          content: {}
    post:
      tags:
      - Response inspection
      summary: Returns a set of response headers from the query string.
      parameters:
      - name: freeform
        in: query
        allowEmptyValue: true
        schema: {}
      responses:
        "200":
          description: Response headers
          content: {}
  /robots.txt:
    get:
      tags:
      - Response formats
      summary: Returns some robots.txt rules.
      responses:
        "200":
          description: Robots file
          content: {}
  /status/{codes}:
    get:
      tags:
      - Status codes
      summary: Return status code or random status code if more than one are given
      parameters:
      - name: codes
        in: path
        required: true
        schema: {}
      responses:
        "100":
          description: Informational responses
          content: {}
        "200":
          description: Success
          content: {}
        "300":
          description: Redirection
          content: {}
        "400":
          description: Client Errors
          content: {}
        "500":
          description: Server Errors
          content: {}
    put:
      tags:
      - Status codes
      summary: Return status code or random status code if more than one are given
      parameters:
      - name: codes
        in: path
        required: true
        schema: {}
      responses:
        "100":
          description: Informational responses
          content: {}
        "200":
          description: Success
          content: {}
        "300":
          description: Redirection
          content: {}
        "400":
          description: Client Errors
          content: {}
        "500":
          description: Server Errors
          content: {}
    post:
      tags:
      - Status codes
      summary: Return status code or random status code if more than one are given
      parameters:
      - name: codes
        in: path
        required: true
        schema: {}
      responses:
        "100":
          description: Informational responses
          content: {}
        "200":
          description: Success
          content: {}
        "300":
          description: Redirection
          content: {}
        "400":
          description: Client Errors
          content: {}
        "500":
          description: Server Errors
          content: {}
    delete:
      tags:
      - Status codes
      summary: Return status code or random status code if more than one are given
      parameters:
      - name: codes
        in: path
        required: true
        schema: {}
      responses:
        "100":
          description: Informational responses
          content: {}
        "200":
          description: Success
          content: {}
        "300":
          description: Redirection
          content: {}
        "400":
          description: Client Errors
          content: {}
        "500":
          description: Server Errors
          content: {}
    patch:
      tags:
      - Status codes
      summary: Return status code or random status code if more than one are given
      parameters:
      - name: codes
        in: path
        required: true
        schema: {}
      responses:
        "100":
          description: Informational responses
          content: {}
        "200":
          description: Success
          content: {}
        "300":
          description: Redirection
          content: {}
        "400":
          description: Client Errors
          content: {}
        "500":
          description: Server Errors
          content: {}
  /stream-bytes/{n}:
    get:
      tags:
      - Dynamic data
      summary: "Streams n random bytes generated with given seed, at given chunk size\
        \ per packet."
      parameters:
      - name: "n"
        in: path
        required: true
        schema: {}
      responses:
        "200":
          description: Bytes.
          content: {}
  /stream/{n}:
    get:
      tags:
      - Dynamic data
      summary: Stream n JSON responses
      parameters:
      - name: "n"
        in: path
        required: true
        schema: {}
      responses:
        "200":
          description: Streamed JSON responses.
          content: {}
  /user-agent:
    get:
      tags:
      - Request inspection
      summary: Return the incoming requests's User-Agent header.
      responses:
        "200":
          description: The request's User-Agent header.
          content: {}
  /uuid:
    get:
      tags:
      - Dynamic data
      summary: Return a UUID4.
      responses:
        "200":
          description: A UUID4.
          content: {}
  /xml:
    get:
      tags:
      - Response formats
      summary: Returns a simple XML document.
      responses:
        "200":
          description: An XML document.
          content: {}
components: {}