README
¶
Webscope
Webscope is lightweight API documentation tool that generates static HTML from markdown and openapi files.
The supported documentation formats are:
- OpenAPI as specified in OpenAPI v3.2.0
- Changelog as specified in keep a changelog
- General documentation from plain markdown files
The generated content can be written to the file system, or served directly from a net/http server.
Warning: Webscope is work-in-progress. Expect missing features or bugs.
Usage
To generate static HTML files, the webscope CLI can be used:
go install gitlab.com/manabug/webscope/cmd/webscope@latest
webscope -i webscope.yaml
An example options file can be viewed at /examples/webscope.yaml.
There is also an option to serve the documentation from a Go HTTP server.
See the http server example.
To see it in action, run the make example-server command, and go to http://localhost:5000/docs/api.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Docs ¶ added in v0.5.0
type Docs struct {
// contains filtered or unexported fields
}
Docs represents the loaded and parsed documentation files
func LoadDocs ¶ added in v0.5.0
LoadDocs reads and parses the documentation sources as based on the options parameter. Returns an error if any of the sources fail to load or parse.
func (*Docs) Handler ¶ added in v0.5.0
Handler returns an HTTP handler that serves the generated documentation HTML.
The handler uses http.ServeMux internally, and sets up the following routes:
- GET /api - Serves the OpenAPI documentation if available
- GET /changelog - Serves the changelog if available
- GET /docs/{name} - Serves individual documentation files, where {name} is the documentation filename without the .md extension
The returned handler uses the enhanced routing patterns introduced in Go 1.22
func (*Docs) WriteToFS ¶ added in v0.5.0
WriteToFS generates static HTML files for all loaded documentation and writes them to the file system. The output directory is specified in options.Options as provided to LoadDocs.
This method will create the output directory if it does not already exist.
Source Files
Directories