@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Color Name API
@base https://api.color.pizza/
@version 1.1.0
@endpoints 7
@toc root(1), health(1), docs(1), v1(1), names(1), lists(1), swatch(1)

@group root
@endpoint GET /
@desc Get API metadata and discovery information
@returns(200) {name: str, version: str, description: str, endpoints: map{colors: str, colorsByPath: str, names: str, lists: str, swatch: str, docs: str, health: str}, documentation: str, source: str} # OK - Returns API metadata

@endgroup

@group health
@endpoint GET /health
@desc Health check endpoint
@returns(200) {status: str, timestamp: str(date-time)} # OK - API is healthy and operational

@endgroup

@group docs
@endpoint GET /v1/docs/
@desc Get API Documentation
@returns(200) OK - Returns the HTML documentation page.

@endgroup

@group v1
@endpoint GET /v1/
@desc Get color names for specific hex values
@returns(200) {colors: [map], paletteTitle: str} # OK
@errors {400: BAD REQUEST, 404: NOT FOUND, 409: CONFLICT - Requested more unique colors than available}

@endgroup

@group names
@endpoint GET /v1/names/
@desc Search for colors by name
@returns(200) {colors: [map]} # OK
@errors {404: NOT FOUND}

@endgroup

@group lists
@endpoint GET /v1/lists/
@desc Get available color name lists
@optional {list: str # The name of a specific color name list to retrieve details for}
@returns(200) OK
@errors {400: BAD REQUEST, 404: NOT FOUND}

@endgroup

@group swatch
@endpoint GET /v1/swatch/
@desc Generate a color swatch for any color
@required {color: str # The hex value of the color to retrieve without '#'}
@optional {name: str # The name of the color to display on the swatch}
@returns(200) OK
@errors {400: BAD REQUEST}

@endgroup

@end