Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -324,7 +324,10 @@ Markdown lives next to what it describes:
| `requests/<service>/<Operation>/README.md` | an operation, above its parameter tables |
| `requests/<service>/docs/<Operation>.md` | the same, flat: one `docs/` folder per service |

A heading made of one code span (`` ## `name` ``) attaches the text under it to that field.
Write whatever markdown you like. The Docs tab also shows the parameters, the request body and each response status
from the spec, below your page; to put one where it belongs in your text, add a comment on a line of its own:
`<!-- specbook: params -->`, `path`, `query`, `headers`, `body`, `responses`, `auth`, `description` or `examples`.
What each field means comes from the spec.

### Try it on any page

Expand Down
4 changes: 2 additions & 2 deletions apps/docs/demo/requests/petstore/GetPetById/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<!-- #region notes -->
Looks a pet up by its id. Use this to check that a pet you added is really there.

## `petId`
The demo's seed pets are 1 to 3, and ones you add start at 1001.

The pet's number, as `Add a pet` returned it. The demo's seed pets are 1 to 3, and ones you add start at 1001.
<!-- specbook: params -->
<!-- #endregion notes -->
2 changes: 1 addition & 1 deletion apps/docs/public/llms.txt
Original file line number Diff line number Diff line change
Expand Up @@ -236,7 +236,7 @@ do not prove it: a request that needs Node builds cleanly and passes in node, an

## Notes beside the code (optional)

Markdown next to what it describes is shown in the UI: `requests/<service>/<Operation>/README.md` for an operation, `<name>.req.md` beside a request, `<name>.seq.md` beside a flow. A heading made of one code span (`` ## `petId` ``) attaches its text to that field.
Markdown next to what it describes is shown in the UI: `requests/<service>/<Operation>/README.md` for an operation, `<name>.req.md` beside a request, `<name>.seq.md` beside a flow. The Docs tab shows the spec's parameters, request body and responses below the page; `<!-- specbook: params -->` (also `path`, `query`, `headers`, `body`, `responses`) on a line of its own puts one where you want it. Field descriptions come from the spec, not from the page.

## Docs

Expand Down
59 changes: 59 additions & 0 deletions apps/docs/src/content/docs/reference/documentation-pages.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
title: Documentation pages
description: Write your own markdown for an operation, a request or a flow, and say where the generated tables go.
---

import Snippet from '../../../components/Snippet.astro'

The Docs tab of an operation shows what the spec says: the description, the parameters, the request body and each
response. A markdown page beside your code adds what the spec does not say. Write whatever you like in it.

## Where a page lives

| File | Documents |
| --- | --- |
| `requests/<service>/<Operation>/README.md` | an operation |
| `requests/<service>/docs/<Operation>.md` | the same, flat: one `docs/` folder per service |
| `requests/<name>.req.md` | the request in `<name>.req.ts` |
| `sequences/<name>.seq.md` | the flow in `<name>.seq.ts` |

A markdown file anywhere else can name what it documents in its front matter, such as `operation: petstore/GetPetById`.
If two pages claim one operation, the first by path is used and the other is reported.

By default the page follows the spec's own description. Put `replace: true` in the front matter to have it stand in
for that description instead.

## Placing the generated tables

Without any markers the page comes first and the tables follow it. To put a table inside your text, write a comment
on a line of its own:

<Snippet file="demo/requests/petstore/GetPetById/README.md" region="notes" title="requests/petstore/GetPetById/README.md" />

| Comment | What appears there |
| --- | --- |
| `<!-- specbook: description -->` | The spec's description of the operation. |
| `<!-- specbook: auth -->` | How to authorize, and which profiles in this project work. |
| `<!-- specbook: params -->` | The path, query and header parameters together. |
| `<!-- specbook: path -->`, `query`, `headers` | One of those on its own. |
| `<!-- specbook: body -->` | The request body. |
| `<!-- specbook: responses -->` | Each response status, with what comes back. |
| `<!-- specbook: examples -->` | The named examples, each opening the Try tab. |

A block you do not place still appears, after your page, in that order. Placing it moves it; it never shows twice.
A comment inside a sentence, or one that names no block, is left alone and shows nothing.

## What the tables hold

Field descriptions come from the spec, so fix them there. The tables list an object's fields and mark the ones that
are required. A field that holds an object, or a list of them, has a [+]: click its row to open it and its plain fields appear
indented one step below it. An object among them is a group of its own at the left, named by its whole path, such as
`address.county`, with its fields below it when you open that in turn. Nothing is ever indented further than one
step. A field that can be one of several shapes names them. A response is a tab for each status, with the spec's text for it and
the type of its body.

## Moving from field notes

Earlier versions turned a heading made of one code span, such as `` ## `petId` ``, into a note on that field. That no
longer happens: the heading is shown as ordinary text. Move the sentence into the spec's description for the field,
or into your own text, and put the table where it should sit with a comment.
2 changes: 1 addition & 1 deletion apps/docs/src/pages/document.astro
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ import Page from '../layouts/Page.astro'
<li>A request: <code>&lt;name&gt;.req.md</code> beside <code>&lt;name&gt;.req.ts</code>.</li>
<li>A flow: <code>&lt;name&gt;.seq.md</code> beside <code>&lt;name&gt;.seq.ts</code>.</li>
<li>Anywhere else: a markdown file whose front matter names what it documents, like <code>operation: petstore/GetPetById</code>.</li>
<li>A field: a heading made of one code span, like <code>## `petId`</code>, attaches its text to that field.</li>
<li>Where the tables go: a comment on a line of its own, like <code>&lt;!-- specbook: params --&gt;</code>, puts the parameters, <code>body</code> or <code>responses</code> there. Without one they follow your text.</li>
</ul>
</details>
</div>
Expand Down
9 changes: 4 additions & 5 deletions apps/example/requests/petstore/AddPet/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,9 @@ store assigns an `id` when you leave it out.
Press **Play** to try it against the mock. The request gives every pet a generated name (`petName`), so
each play sends a new one.

## `name`
## What to send

Shown in the shop's catalogue, so keep it under 40 characters. Names are not unique.
The name is shown in the shop's catalogue, so keep it under 40 characters. Names are not unique. Give at
least one photo URL: the demo store does not fetch them, so any `https://` address works.

## `photoUrls`

At least one URL. The demo store does not fetch them, so any `https://` address works.
<!-- specbook: body -->
2 changes: 1 addition & 1 deletion packages/cli/agent-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -236,4 +236,4 @@ do not prove it: a request that needs Node builds cleanly and passes in node, an

## Notes beside the code (optional)

Markdown next to what it describes is shown in the UI: `requests/<service>/<Operation>/README.md` for an operation, `<name>.req.md` beside a request, `<name>.seq.md` beside a flow. A heading made of one code span (`` ## `petId` ``) attaches its text to that field.
Markdown next to what it describes is shown in the UI: `requests/<service>/<Operation>/README.md` for an operation, `<name>.req.md` beside a request, `<name>.seq.md` beside a flow. The Docs tab shows the spec's parameters, request body and responses below the page; `<!-- specbook: params -->` (also `path`, `query`, `headers`, `body`, `responses`) on a line of its own puts one where you want it. Field descriptions come from the spec, not from the page.
1 change: 1 addition & 0 deletions packages/codegen/src/browser.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ export type {
ManifestOperation,
ManifestSecurityScheme,
OperationMeta,
ResponseDoc,
} from './build'
export { generateFromDoc, logoOf } from './build'

Expand Down
31 changes: 30 additions & 1 deletion packages/codegen/src/build.ts
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,13 @@ interface ExampleDoc {
body?: unknown
}

/** What `docs/<id>.json` says about one response, for the Docs tab. */
export interface ResponseDoc {
description?: string
/** the media type the body is written in, as the spec names it */
contentType?: string
}

export interface ManifestOperation {
id: string
method: string
Expand Down Expand Up @@ -174,6 +181,7 @@ function findJsonLike(content: Record<string, any> | undefined) {
schema: content[mime].schema as Schema | undefined,
encoding: enc,
media: content[mime],
mime,
}
}
const json = Object.keys(content).find((m) => /json/.test(m))
Expand All @@ -182,13 +190,15 @@ function findJsonLike(content: Record<string, any> | undefined) {
schema: content[json].schema as Schema | undefined,
encoding: 'json',
media: content[json],
mime: json,
}
const binary = Object.keys(content).find((m) => BINARY_MIME.test(m))
if (binary)
return {
schema: content[binary].schema as Schema | undefined,
encoding: 'binary',
media: content[binary],
mime: binary,
mediaType: binary,
}
// A wildcard stands for whatever the server sends, and a framework that is not told what it produces
Expand All @@ -201,6 +211,7 @@ function findJsonLike(content: Record<string, any> | undefined) {
schema,
encoding: file ? 'binary' : 'json',
media: content[any],
mime: any,
...(file ? { mediaType: any } : {}),
}
}
Expand Down Expand Up @@ -544,14 +555,28 @@ function generateAll(
let defaultSchema: Schema | undefined
const responseSchemas: Record<string, Schema> = {}
const mockVariants: NonNullable<ManifestOperation['mockVariants']> = {}
const responseDocs: Record<string, ResponseDoc> = {}
let defaultDoc: ResponseDoc | undefined
const docOf = (res: any, found: { mime?: string } | undefined): ResponseDoc | undefined => {
const description =
typeof res?.description === 'string' && res.description.trim()
? res.description.trim()
: undefined
const contentType = found?.mime ?? Object.keys(res?.content ?? {})[0]
return description || contentType
? { ...(description ? { description } : {}), ...(contentType ? { contentType } : {}) }
: undefined
}
let defaultVariants: ManifestOperation['mockVariants'] extends infer M
? M extends Record<string, infer V>
? V | undefined
: never
: never
for (const [code, rawRes] of Object.entries<any>(op.responses ?? {})) {
if (code === 'default') {
const found = findJsonLike(resolveAny<any>(rawRes)?.content)
const defaultRes = resolveAny<any>(rawRes)
const found = findJsonLike(defaultRes?.content)
defaultDoc = docOf(defaultRes, found)
if (found?.schema) {
hasDefault = true
if (ts) defaultType = tsType(found.schema, ' ', 'T.')
Expand All @@ -569,6 +594,8 @@ function generateAll(
const res = resolveAny<any>(rawRes)
const found = findJsonLike(res?.content)
statuses.push(Number(code))
const responseDoc = docOf(res, found)
if (responseDoc) responseDocs[code] = responseDoc
if (found?.schema) responseSchemas[code] = toJsonSchema(found.schema, `${defsId}#/$defs/`)
if (ts)
responseTypes.push(
Expand All @@ -587,6 +614,7 @@ function generateAll(
for (const st of DEFAULT_ERROR_STATUSES) {
if (statuses.includes(st)) continue
statuses.push(st)
if (defaultDoc) responseDocs[String(st)] = defaultDoc
if (defaultSchema) responseSchemas[String(st)] = defaultSchema
if (defaultVariants) mockVariants[String(st)] = defaultVariants
if (defaultType) responseTypes.push(`${st}: ${defaultType}`)
Expand Down Expand Up @@ -746,6 +774,7 @@ ${jsdoc({ description: [...new Set([op.summary, op.description].filter(Boolean))
content: `${JSON.stringify({
...(op.description && op.description !== summary ? { description: op.description } : {}),
examples: docs.map((d) => ({ name: d.name, title: d.title, source: d.source })),
...(Object.keys(responseDocs).length ? { responses: responseDocs } : {}),
})}\n`,
})
operations.push({
Expand Down
66 changes: 66 additions & 0 deletions packages/codegen/test/generate.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1328,3 +1328,69 @@ describe('round 2: what the spec still says', () => {
expect(synthesize(string, none, 0, [], 'master_branch')).toBe('main')
})
})

describe('what each response is, for the docs page', () => {
const docs = (files: { path: string; content: string }[], id: string) =>
JSON.parse(files.find((f) => f.path === `docs/${id}.json`)?.content ?? 'null')

it('keeps the description and media type of every status', async () => {
const { files } = await generate({ spec: fx('bookstore.json'), service: 'books' })
expect(docs(files, 'ListShelf').responses).toEqual({
'200': { description: 'The shelf', contentType: 'application/json' },
'409': { description: 'Not available', contentType: 'application/json' },
})
})

it('keeps the description of a status that has no body', async () => {
const { files } = await generate({ spec: fx('petstore3.json'), service: 'petstore' })
const responses = docs(files, 'GetPetById').responses
expect(responses['400']).toEqual({ description: 'Invalid ID supplied' })
expect(responses['200'].contentType).toBe('application/json')
})

it('gives a default response to every status it stands for, and names non-JSON media types', async () => {
const dir = await mkdtemp(join(tmpdir(), 'specbook-docs-'))
dirs.push(dir)
const spec = join(dir, 'spec.json')
await writeFile(
spec,
JSON.stringify({
openapi: '3.0.3',
info: { title: 't', version: '1' },
paths: {
'/a': {
get: {
operationId: 'GetA',
responses: {
'200': {
description: 'Fine',
content: { 'text/csv': { schema: { type: 'string' } } },
},
default: {
description: 'Something went wrong',
content: {
'application/json': {
schema: { type: 'object', properties: { message: { type: 'string' } } },
},
},
},
},
},
},
},
}),
)
const { files } = await generate({ spec, service: 'a' })
const responses = docs(files, 'GetA').responses
expect(responses['200']).toEqual({ description: 'Fine', contentType: 'text/csv' })
for (const code of [400, 401, 402, 403, 404, 409, 422, 429, 500])
expect(responses[String(code)]).toEqual({
description: 'Something went wrong',
contentType: 'application/json',
})
const schemas = JSON.parse(
files.find((f) => f.path === 'schemas/GetA.responses.schema.json')?.content ?? '{}',
)
expect(schemas['200']).toBeUndefined()
})
})
14 changes: 0 additions & 14 deletions packages/ui/src/fielddoc.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
import { type FieldSection, noteKey } from './panel/fieldnotes-split'
import {
type Defs,
describe,
Expand All @@ -19,8 +18,6 @@ export interface FieldDoc {
required: boolean
enum?: string[]
description?: string
/** the project's own note for this field (HTML), shown after the spec's description */
note?: string
/** what the enclosing object says about itself, shown when the field has no description */
parent?: string
deprecated?: boolean
Expand Down Expand Up @@ -80,14 +77,3 @@ export function fieldDoc(
export function keyPath(key: string): KeyPath {
return (key.match(/[^[\]]+/g) ?? [key]).map((s) => (/^\d+$/.test(s) ? Number(s) : s))
}

/** Adds the project's note for `path` in `section` (see `README.md` field sections), when there is one. */
export function withNote(
doc: FieldDoc | undefined,
notes: Map<string, string> | undefined,
section: FieldSection,
path: string,
): FieldDoc | undefined {
const note = doc && notes?.get(noteKey(section, path))
return doc && note ? { ...doc, note } : doc
}
38 changes: 35 additions & 3 deletions packages/ui/src/markdown.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,14 +21,46 @@ function inline(text: string): string {
return s.replace(/\uE000(\d+)\uE000/g, (_m, i: string) => codes[Number(i)] ?? '')
}

/**
* The HTML some specs write their descriptions in (Stripe's are `<p>…</p>`) as the markdown this file reads: the tags
* that mean something become their markdown, and any other known tag is dropped, so none is shown as text. Text that
* only looks like a tag (`<name>`) and fenced code are left alone.
*/
export function fromHtml(src: string): string {
return src
.split(/(```[\s\S]*?```)/)
.map((part, i) =>
i % 2
? part
: part
.replace(/<\/p>\s*<p[^>]*>/gi, '\n\n')
.replace(/<br\s*\/?>/gi, '\n')
.replace(/<code[^>]*>([\s\S]*?)<\/code>/gi, '`$1`')
.replace(/<(strong|b)(\s[^>]*)?>([\s\S]*?)<\/\1>/gi, '**$3**')
.replace(/<(em|i)(\s[^>]*)?>([\s\S]*?)<\/\1>/gi, '*$3*')
.replace(
/<a\s[^>]*href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi,
(_m, href: string, text: string) => `[${text}](${href})`,
)
.replace(/<li[^>]*>/gi, '\n- ')
.replace(
/<\/?(p|ul|ol|li|div|span|h[1-6]|table|thead|tbody|tr|td|th)(\s[^>]*)?>/gi,
'\n',
)
.replace(/\n{3,}/g, '\n\n'),
)
.join('')
.trim()
}

/**
* A small, safe markdown subset for descriptions: paragraphs, headings, bullet and numbered lists, fenced
* code, and inline code, bold, italics and links. Everything is HTML-escaped first, and only http(s) and
* mailto links are linked, so descriptions from a spec or a sequence can be rendered without trusting them.
*/
export function markdownToHtml(src: string | undefined): string {
if (!src) return ''
const lines = src.replace(/\r\n?/g, '\n').split('\n')
const lines = fromHtml(src).replace(/\r\n?/g, '\n').split('\n')
const out: string[] = []
let para: string[] = []
let list: { tag: 'ul' | 'ol'; items: string[] } | undefined
Expand Down Expand Up @@ -100,7 +132,7 @@ export function markdownToHtml(src: string | undefined): string {
/** Markdown reduced to readable plain text: links keep their label, markers and fences disappear. */
export function plainText(src: string | undefined): string {
if (!src) return ''
return src
return fromHtml(src)
.replace(/```[\s\S]*?```/g, ' ')
.replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
.replace(/^#{1,6}\s+/gm, '')
Expand All @@ -113,7 +145,7 @@ export function plainText(src: string | undefined): string {

export function firstParagraph(src: string | undefined): string {
if (!src) return ''
return (src.trim().split(/\n\s*\n/)[0] ?? '').replace(/\s*\n\s*/g, ' ').trim()
return (fromHtml(src).split(/\n\s*\n/)[0] ?? '').replace(/\s*\n\s*/g, ' ').trim()
}

/** Inline markup only (code, bold, italics, links) in already-safe HTML, for a single line or cell. */
Expand Down
Loading
Loading