498 lines
15 KiB
YAML
498 lines
15 KiB
YAML
openapi: 3.1.1
|
|
info:
|
|
title: Recipe API
|
|
description: Programmatic access to a database of recipes. Users can publish and find recipes.
|
|
version: 1.0.0
|
|
license:
|
|
name: MIT
|
|
url: https://opensource.org/licenses/MIT
|
|
servers:
|
|
- url: https://api.recipes.bitfield.eu/v1
|
|
security: []
|
|
tags:
|
|
- name: Recipe
|
|
description: Steps and ingredients for preparing a dish
|
|
- name: Account
|
|
description: Access to protected operations
|
|
paths:
|
|
/recipe/new:
|
|
post:
|
|
tags:
|
|
- Recipe
|
|
summary: Add a recipe
|
|
operationId: addRecipe
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Recipe'
|
|
examples:
|
|
recipeIn:
|
|
$ref: '#/components/examples/HummusV1In'
|
|
required: true
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Recipe'
|
|
examples:
|
|
recipeOut:
|
|
$ref: '#/components/examples/HummusV1Out'
|
|
'400':
|
|
description: Bad Request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemDetail'
|
|
'401':
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemDetail'
|
|
'403':
|
|
description: Forbidden
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemDetail'
|
|
'404':
|
|
description: Not Found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemDetail'
|
|
security:
|
|
- httpBasic: []
|
|
/recipe/search:
|
|
get:
|
|
tags:
|
|
- Recipe
|
|
summary: Find recipes
|
|
operationId: FindRecipes
|
|
parameters:
|
|
- name: category
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: Category name filter (equals, ignores case)
|
|
- name: recipe
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: Recipe name filter (contains, ignores case)
|
|
- name: limit
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
minimum: 1
|
|
maximum: 100
|
|
description: Maximum number of recipes to return
|
|
- name: offset
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
minimum: 0
|
|
description: Index into result set from where recipes will start to be returned
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Recipe'
|
|
examples:
|
|
dipsOut:
|
|
$ref: '#/components/examples/DipsOut'
|
|
'400':
|
|
description: Bad Request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemDetail'
|
|
'404':
|
|
description: Not Found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemDetail'
|
|
/recipe/{recipeId}:
|
|
get:
|
|
tags:
|
|
- Recipe
|
|
summary: Get a recipe
|
|
operationId: GetRecipe
|
|
parameters:
|
|
- $ref: '#/components/parameters/{recipeId}'
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Recipe'
|
|
examples:
|
|
recipeOut:
|
|
$ref: '#/components/examples/HummusV1Out'
|
|
'400':
|
|
description: Bad Request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemDetail'
|
|
'404':
|
|
description: Not Found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemDetail'
|
|
put:
|
|
tags:
|
|
- Recipe
|
|
summary: Update a recipe
|
|
operationId: UpdateRecipe
|
|
parameters:
|
|
- $ref: '#/components/parameters/{recipeId}'
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Recipe'
|
|
examples:
|
|
recipeIn:
|
|
$ref: '#/components/examples/HummusV2In'
|
|
required: true
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Recipe'
|
|
examples:
|
|
recipeOut:
|
|
$ref: '#/components/examples/HummusV2Out'
|
|
'400':
|
|
description: Bad Request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemDetail'
|
|
'401':
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemDetail'
|
|
'403':
|
|
description: Forbidden
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemDetail'
|
|
'404':
|
|
description: Not Found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemDetail'
|
|
security:
|
|
- httpBasic: []
|
|
delete:
|
|
tags:
|
|
- Recipe
|
|
summary: Remove a recipe
|
|
operationId: RemoveRecipe
|
|
parameters:
|
|
- $ref: '#/components/parameters/{recipeId}'
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
'400':
|
|
description: Bad Request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemDetail'
|
|
'401':
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemDetail'
|
|
'403':
|
|
description: Forbidden
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemDetail'
|
|
'404':
|
|
description: Not Found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemDetail'
|
|
security:
|
|
- httpBasic: []
|
|
/account/register:
|
|
post:
|
|
tags:
|
|
- Account
|
|
summary: Register an account
|
|
operationId: RegisterAccount
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Account'
|
|
examples:
|
|
accountIn:
|
|
$ref: '#/components/examples/AccountIn'
|
|
required: true
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
'400':
|
|
description: Bad Request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemDetail'
|
|
components:
|
|
securitySchemes:
|
|
httpBasic:
|
|
type: http
|
|
scheme: basic
|
|
schemas:
|
|
Id:
|
|
type: integer
|
|
format: int64
|
|
NonBlankString:
|
|
type: string
|
|
pattern: ^(.|\s)*\S(.|\s)*$
|
|
DateTime:
|
|
type: string
|
|
format: date-time
|
|
Recipe:
|
|
type: object
|
|
properties:
|
|
id:
|
|
$ref: '#/components/schemas/Id'
|
|
readOnly: true
|
|
description: Unique identifier of the recipe
|
|
name:
|
|
$ref: '#/components/schemas/NonBlankString'
|
|
description: Name
|
|
description:
|
|
$ref: '#/components/schemas/NonBlankString'
|
|
description: Description
|
|
changedAt:
|
|
$ref: '#/components/schemas/DateTime'
|
|
readOnly: true
|
|
description: Last point in time when the recipe was changed
|
|
categories:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/NonBlankString'
|
|
description: Category names
|
|
ingredients:
|
|
type: array
|
|
minItems: 1
|
|
items:
|
|
$ref: '#/components/schemas/NonBlankString'
|
|
description: Step descriptions
|
|
steps:
|
|
type: array
|
|
minItems: 1
|
|
items:
|
|
$ref: '#/components/schemas/NonBlankString'
|
|
description: Ingredient names
|
|
required:
|
|
- name
|
|
- description
|
|
- categories
|
|
- ingredients
|
|
- steps
|
|
ProblemDetail:
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
description: URI reference that identifies the problem type.
|
|
format: uri
|
|
status:
|
|
type: integer
|
|
description: HTTP status code generated by the origin server for this occurrence of the problem.
|
|
format: int32
|
|
title:
|
|
type: string
|
|
description: Short, human-readable summary of the problem type. It should not change from occurrence to occurrence of the problem, except for purposes of localization.
|
|
detail:
|
|
type: string
|
|
description: Human-readable explanation specific to this occurrence of the problem.
|
|
instance:
|
|
type: string
|
|
description: URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
|
|
properties:
|
|
type: object
|
|
description: Map for additional, non-standard properties
|
|
required:
|
|
- title
|
|
Email:
|
|
type: string
|
|
format: email
|
|
description: Email address
|
|
Password:
|
|
type: string
|
|
format: password
|
|
minLength: 8
|
|
description: Password
|
|
Account:
|
|
type: object
|
|
properties:
|
|
email:
|
|
$ref: '#/components/schemas/Email'
|
|
password:
|
|
$ref: '#/components/schemas/Password'
|
|
required:
|
|
- email
|
|
- password
|
|
examples:
|
|
HummusV1In:
|
|
summary: Hummus recipe
|
|
value:
|
|
name: Hummus
|
|
description: Hummus, is a Levantine dip, spread, or savory dish made from cooked, mashed chickpeas blended with tahini, lemon juice, and garlic.
|
|
categories:
|
|
- Dip
|
|
- Spread
|
|
ingredients:
|
|
- Chickpeas
|
|
- Tahini
|
|
- Olive oil
|
|
- Lemon juice
|
|
- Garlic
|
|
steps:
|
|
- Combine chickpeas, tahini, olive oil, lemon juice, garlic, and salt in a food processor.
|
|
- Blend until smooth, slowly adding cold water until you reach a creamy consistency.
|
|
- Taste and adjust seasoning if needed.
|
|
HummusV1Out:
|
|
summary: Hummus recipe
|
|
value:
|
|
id: 1729
|
|
name: Hummus
|
|
description: Hummus, is a Levantine dip, spread, or savory dish made from cooked, mashed chickpeas blended with tahini, lemon juice, and garlic.
|
|
changedAt: '2025-08-08T15:35:10.294411Z'
|
|
categories:
|
|
- Dip
|
|
- Spread
|
|
ingredients:
|
|
- Chickpeas
|
|
- Tahini
|
|
- Olive oil
|
|
- Lemon juice
|
|
- Garlic
|
|
steps:
|
|
- Combine chickpeas, tahini, olive oil, lemon juice, garlic, and salt in a food processor.
|
|
- Blend until smooth, slowly adding cold water until you reach a creamy consistency.
|
|
- Taste and adjust seasoning if needed.
|
|
DipsOut:
|
|
summary: Dip category search
|
|
value:
|
|
- id: 3
|
|
name: Muhammara
|
|
description: Muhammara is a vibrant and flavorful dip or spread from the Middle East, particularly popular in Syrian and Turkish cuisine. It's made primarily from roasted red bell peppers, walnuts, breadcrumbs, and pomegranate molasses.
|
|
changedAt: '2025-08-08T16:24:44.673034Z'
|
|
categories:
|
|
- Dip
|
|
ingredients:
|
|
- Pomegranate molasses
|
|
- Red bell peppers
|
|
- Bread crumbs
|
|
- Cumin
|
|
- Chili flakes
|
|
- Garlic
|
|
- Walnuts
|
|
- Lemon juice
|
|
steps:
|
|
- Roast whole bell peppers in an oven or air fryer and wait until blackened on the outside.
|
|
- Put the peppers in a bowl cover them with to let steam and cool down
|
|
- Remove core seeds, and skins
|
|
- Combine all the ingredients in a food processor.
|
|
- Process until mostly smooth but with a little texture remaining.
|
|
- Taste and adjust flavor as needed (lemon for acidity, pomegranate molasses for sweetness)
|
|
- id: 2
|
|
name: Hummus
|
|
description: Hummus, is a Levantine dip, spread, or savory dish made from cooked, mashed chickpeas blended with tahini, lemon juice, and garlic.
|
|
changedAt: '2025-08-08T16:24:44.579213Z'
|
|
categories:
|
|
- Dip
|
|
ingredients:
|
|
- Chickpeas
|
|
- Tahini
|
|
- Lemon juice
|
|
- Garlic
|
|
steps:
|
|
- Combine chickpeas, tahini, lemon juice, garlic, and salt in a food processor.
|
|
- Blend until smooth, slowly adding cold water until you reach a creamy consistency.
|
|
- Taste and adjust seasoning if needed.
|
|
HummusV2In:
|
|
summary: Hummus recipe update
|
|
value:
|
|
name: Hummus
|
|
description: Hummus, is a Levantine dip, spread, or savory dish made from cooked, mashed chickpeas blended with tahini, lemon juice, and garlic.
|
|
categories:
|
|
- Dip
|
|
- Spread
|
|
ingredients:
|
|
- Chickpeas
|
|
- Tahini
|
|
- Lemon juice
|
|
- Garlic
|
|
steps:
|
|
- Combine chickpeas, tahini, lemon juice, garlic, and salt in a food processor.
|
|
- Blend until smooth, slowly adding cold water until you reach a creamy consistency.
|
|
- Taste and adjust seasoning if needed.
|
|
HummusV2Out:
|
|
summary: Hummus recipe update
|
|
value:
|
|
id: 1729
|
|
name: Hummus
|
|
description: Hummus, is a Levantine dip, spread, or savory dish made from cooked, mashed chickpeas blended with tahini, lemon juice, and garlic.
|
|
changedAt: '2025-08-09T12:48:32.134821Z'
|
|
categories:
|
|
- Dip
|
|
- Spread
|
|
ingredients:
|
|
- Chickpeas
|
|
- Tahini
|
|
- Lemon juice
|
|
- Garlic
|
|
steps:
|
|
- Combine chickpeas, tahini, lemon juice, garlic, and salt in a food processor.
|
|
- Blend until smooth, slowly adding cold water until you reach a creamy consistency.
|
|
- Taste and adjust seasoning if needed.
|
|
AccountIn:
|
|
summary: Account registration
|
|
value:
|
|
email: ada@example.com
|
|
password: FBR5h0L1ENA3edctgDIEnxSvFdR0
|
|
parameters:
|
|
'{recipeId}':
|
|
name: recipeId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
$ref: '#/components/schemas/Id'
|
|
description: Unique identifier of the recipe
|