Skip to content

Latest commit

 

History

History
139 lines (102 loc) · 2.99 KB

README.asciidoc

File metadata and controls

139 lines (102 loc) · 2.99 KB
Raw

GOpenAPI

CircleCI

An OpenAPI utility for Go. This project aims to bring support of OpenAPI v3.

Usage

$ gopenapi [command] [arg]

Generating Specifications From Code

gopenapi generate spec [optional path] [flags]

Args

[optional path]   Optionally specify the directory in which to search. Accepts absolute paths. Relative paths are relative to the current directory. (default ".")

Flags

-f, --format string   The format of the output. May be json or yaml (default "json")
-o, --output string   Where the output should be directed. May be '-' (stdout) or a path to a file (default "-")

Format

Code is annotated with different types of comments that help generate the spec.

The comment contains a keyword that specifies the type of the OpenAPI element.

The content of the comment should be a valid YAML OpenAPI element

Info

Begin a comment with gopenapi:info and follow up with a YAML representation of the OpenAPI Info element.

This element is then set to the info property of the specification.

package main

/*
gopenapi:info
title: The App Name
version: 1.0
description: |-
  The app description
contact:
  name: Jimbob Jones
  url: https://jones.com
  email: jimbob@jones.com
license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
*/
func main() {
}
Path

Begin a comment with gopenapi:path and follow up with a YAML representation of the OpenAPI PathItem element.

This element is then appended to the paths property of the specification.

package main

/*
gopenapi:path
/ping:
  get:
    responses:
      200:
        description: |-
          The default response of "ping"
        content:
          text/plain:
            example: pong
*/
func ControllerFunc() {
}
Object Schema

Annotate a struct with a gopenapi:objectSchema.

The generated ObjectSchema element will be appended to the components.schemas property of the specification.

//gopenapi:objectSchema
type RootModel struct {
	IntField    int64  `json:"intField"`
	StringField string `json:"stringField"`
}

// This struct will be ignored
type IgnoredModel struct {
}

//gopenapi:objectSchema
type AliasedModels []*AliasedModel // This alias will appear as a schema too

//gopenapi:objectSchema
type AliasedModel struct {
	IgnoredField string `json:"-"` // This field will be ignored
	TimeField    time.Time
}
Parameter

Annotate a const or a var with a gopenapi:parameter.

The annotated field will be appended to the components.parameters property of the specification.

/*
gopenapi:parameter
in: path
required: true
content:
  text/plain:
    example: 30
*/
const Limit = "limit"

The name of the field (Limit) will be the parameter identifier and the value of the field (limit) will be the name of the parameter.