README
¶
go-oas-extract
go-oas-extract is a tool for extracting specially tagged comments in Go source code and transforming it into valid Open API 3.0.3 Specification.
Tagged comments start with a blank line containing +extract.
Both grouped line comments (//) and block comments (/* */) are supported.
Installation
Go 1.16:
go install github.com/jacobkring/go-oas-extract@latest
Usage
Simply tag comments in your Go source code with +extract as the first
line of your comment. For example,
package main
// +extract
// API Documentation
// =================
//
// (TODO: add documentation)
Then run the doc-extract command, providing it with a directory of
Go source files and an output file:
doc-extract ./example example.txt
Source files are processed in lexicographic order, except that a file
named doc.go gets highest priority. Comments within a file are
processed in the order they appear.
This predictable ordering allows you to add, for instance, a header to
the output file by adding it to doc.go.
Example
The example directory contains an example using API
Blueprint.
Motivation
There weren't any existing libraries that I could find that would extract inline comments from a Go API and transform them into a valid Open API 3.0+ specification. I was using https://github.com/go-swagger/go-swagger and there is no intention for that project to support anything other than Open API 2.0.
Contributing
Issues and pull requests are welcome. When filing a PR, please make
sure the code has been run through gofmt and that the tests pass.
Notes
Initially forked from https://github.com/joeshaw/doc-extract to provide a basis for text extraction.
License
MIT
Documentation
¶
Overview ¶
Source files are processed in lexicographic order, except that a file named doc.go is always processed first. Comments within a file are extracted in the order they appear. This predictable order allows you to add, for instance, a header to the output file by adding it to doc.go.
Source Files
Directories