Conversation
| @@ -105,9 +132,9 @@ index 44f29a4..436a780 100644 | |||
|
|
|||
| ## Usage | |||
|
|
|||
| `oapi-codegen` is largely configured using a YAML configuration file, to simplify the number of flags that users need to remember, and to make reading the `go:generate` command less daunting. | |||
There was a problem hiding this comment.
it is still largely configured through config file - a number of folks are still using the (deprecated) CLI options - maybe we need to make it clearer that it is deprecated?
| @@ -382,2423 +410,464 @@ We can see that this provides the best means to focus on the implementation of t | |||
|
|
|||
| `oapi-codegen` shines by making it fairly straightforward (note that this is a purposeful choice of wording here - we want to avoid words like "easy") to generate the server-side boilerplate for a backend API. | |||
|
|
|||
| Below you can find the supported servers, and more information about how to implement a server using them. | |||
| Below you can find the supported HTTP router packages, and more information about how to implement a server on top of each router. | |||
There was a problem hiding this comment.
"HTTP router" may be the more "technically correct" term, but we may also want to refer to server here, for folks who don't know that in Go they're called routers
jamietanna
left a comment
jamietanna
left a comment
There was a problem hiding this comment.
If we're going to split the documentation across files, that's probably good - I've had grumblings in the past that GitHub's generated table of contents doesn't actually scroll so folks can't scroll through all the headers - but we should consider what this means for the docs in pkg.go.dev, which I believe only pull from README.md - do we need to make sure there's a subset of docs available for pkg.go.dev? Does docs/... work there?
I think if we're going to use Markdown-committed table of contents, we need a way to keep them up-to-date (via automation).
I guess you've generated them one-time using Claude, but to make it consistent, this needs to be automatable + validated in CI
Also, the reason for using an HTML table over Markdown is that it's easier to add new entries without worrying about formatting (should we be introducing whitespace to make sure all the Markdown table columns line up?) etc
(Haven't yet fully reviewed the different pages - will do shortly)
2 participants
Break up the README.md into smaller chunks, and add more docs about the configuration file. All the router examples and the config docs go into their own files under the docs/ directory.
Added a table of contents
For code review, it might be easier to peruse the docs in my source branch, rather than trying to understand it from diffs.