search

mccutchen / go-httpbin

A reasonably complete and well-tested golang port of httpbin, with zero dependencies outside the go stdlib.
https://httpbingo.org
MIT License
596 stars 124 forks source link

Question: swagger schema #177

Open titpetric opened 4 months ago

titpetric commented 4 months ago

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.

mccutchen commented 4 months ago

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 commented 2 weeks ago

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

OpenAPI 3.0.x for go-httpbin ```yaml 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: {} ```