docs

README

http-api-docs was moved to ipfs-docs

This project got moved to https://github.com/ipfs/ipfs-docs/tree/main/tools/http-api-docs

See rationale in https://github.com/ipfs/ipfs-docs/issues/267 and https://github.com/ipfs/ipfs-docs/pull/875

Documentation

Overview

Package docs can be used to gather go-ipfs commands and automatically generate documentation or tests.

Index

• Constants
• Variables
• func GenerateDocs(api []*Endpoint, formatter Formatter) string
• func IPFSVersion() string
• type Argument
• type Endpoint
  • func AllEndpoints() []*Endpoint
  • func Endpoints(name string, cmd *cmds.Command) (endpoints []*Endpoint)
• type Formatter
• type MarkdownFormatter
  • func (md *MarkdownFormatter) GenerateArgumentsBlock(args []*Argument, opts []*Argument) string
  • func (md *MarkdownFormatter) GenerateBodyBlock(args []*Argument) string
  • func (md *MarkdownFormatter) GenerateEndpointBlock(endp *Endpoint) string
  • func (md *MarkdownFormatter) GenerateExampleBlock(endp *Endpoint) string
  • func (md *MarkdownFormatter) GenerateIndex(endps []*Endpoint) string
  • func (md *MarkdownFormatter) GenerateIntro() string
  • func (md *MarkdownFormatter) GenerateResponseBlock(response string) string

Constants

const APIPrefix = "/api/v0"

const IndentLevel = 4

How much to indent when generating the response schemas

const MaxIndent = 20

Failsafe when traversing objects containing objects of the same type

Variables

var IgnoreEndpoints = map[string]bool{}

A map of single endpoints to be skipped (subcommands are processed though).

var JsondocGlossary = jsondoc.NewGlossary().
	WithSchema(new(cid.Cid), jsondoc.Object{"/": "<cid-string>"}).
	WithName(new(multiaddr.Multiaddr), "multiaddr-string").
	WithName(new(peer.ID), "peer-id").
	WithSchema(new(peer.AddrInfo),
		jsondoc.Object{"ID": "peer-id", "Addrs": []string{"<multiaddr-string>"}})

Functions

func GenerateDocs

func GenerateDocs(api []*Endpoint, formatter Formatter) string

GenerateDocs uses a formatter to generate documentation for every endpoint

func IPFSVersion

func IPFSVersion() string

Types

type Argument

type Argument struct {
	Endpoint    string
	Name        string
	Description string
	Type        string
	Required    bool
	Default     string
}

Argument defines an IPFS RPC API endpoint argument.

type Endpoint

type Endpoint struct {
	Name        string
	Arguments   []*Argument
	Options     []*Argument
	Description string
	Response    string
	Group       string
}

Endpoint defines an IPFS RPC API endpoint.

func AllEndpoints

func AllEndpoints() []*Endpoint

AllEndpoints gathers all the endpoints from go-ipfs.

func Endpoints

func Endpoints(name string, cmd *cmds.Command) (endpoints []*Endpoint)

Endpoints receives a name and a go-ipfs command and returns the endpoints it defines] (sorted). It does this by recursively gathering endpoints defined by subcommands. Thus, calling it with the core command Root generates all the endpoints.

type Formatter

type Formatter interface {
	GenerateIntro() string
	GenerateIndex(endp []*Endpoint) string
	GenerateEndpointBlock(endp *Endpoint) string
	GenerateArgumentsBlock(args []*Argument, opts []*Argument) string
	GenerateBodyBlock(args []*Argument) string
	GenerateResponseBlock(response string) string
	GenerateExampleBlock(endp *Endpoint) string
}

Formatter allows to implement generation of docs in different formats.

type MarkdownFormatter

type MarkdownFormatter struct{}

MarkdownFormatter implements a markdown doc generator. It is used to generate the IPFS website API reference at https://github.com/ipfs/website/blob/master/content/pages/docs/api.md

func (*MarkdownFormatter) GenerateArgumentsBlock

func (md *MarkdownFormatter) GenerateArgumentsBlock(args []*Argument, opts []*Argument) string

func (*MarkdownFormatter) GenerateBodyBlock

func (md *MarkdownFormatter) GenerateBodyBlock(args []*Argument) string

func (*MarkdownFormatter) GenerateEndpointBlock

func (md *MarkdownFormatter) GenerateEndpointBlock(endp *Endpoint) string

func (*MarkdownFormatter) GenerateExampleBlock

func (md *MarkdownFormatter) GenerateExampleBlock(endp *Endpoint) string

func (*MarkdownFormatter) GenerateIndex

func (md *MarkdownFormatter) GenerateIndex(endps []*Endpoint) string

func (*MarkdownFormatter) GenerateIntro

func (md *MarkdownFormatter) GenerateIntro() string

func (*MarkdownFormatter) GenerateResponseBlock

func (md *MarkdownFormatter) GenerateResponseBlock(response string) string