openapi

package
v0.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 3, 2019 License: MIT Imports: 1 Imported by: 0

README

OpenAPI

Develop

  • use swagger-ui to valid and visualize generated YAML/json

Known issues

  • need to use pointer to avoid invalid recursive type because size of struct must be know at compile time, its fields can not contains the struct itself (indirect inclusion is also not possible)

Reference

Documentation

Overview

Package openapi defines structs for OpenAPI v3 schema

The example specs snippets in the comments are directly copied from https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md

Index

Constants

View Source 
const Version = "3.0.2"

Variables

This section is empty.

Functions

This section is empty.

Types

type Components 

type Components struct {
	Schemas   map[string]*SchemaOrRef  `json:"schemas" yaml:"schemas"`
	Responses map[string]ResponseOrRef `json:"responses,omitempty" yaml:"responses,omitempty"`
	// TODO: parameters
	// TODO: examples
	RequestBodies map[string]RequestBodyOrRef `json:"requestBodies,omitempty" yaml:"requestBodies,omitempty"`
}

Components contains reusable objects that can be referenced https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#componentsObject

type Contact 

type Contact struct {
	Name  string `json:"name" yaml:"name"`
	Url   string `json:"url" yaml:"url"`
	Email string `json:"email" yaml:"email"`
}

Contact is optional, it contains contact info of exposed API https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#contact-object 

{
 "name": "API Support",
 "url": "http://www.example.com/support",
 "email": "support@example.com"
}

type Document 

type Document struct {
	Openapi      string          `json:"openapi" yaml:"openapi"`
	Info         Info            `json:"info" yaml:"info"`
	Servers      []Server        `json:"servers" yaml:"servers"`
	Tags         []Tag           `json:"tags,omitempty" yaml:"tags,omitempty"`
	ExternalDocs *ExternalDoc    `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	Paths        map[string]Path `json:"paths" yaml:"paths"`
	Components   Components      `json:"components,omitempty" yaml:"components,omitempty"`
	Security     *Security       `json:"security,omitempty" yaml:"security,omitempty"`
}

Document is the full API doc - paths defines routes and their operations - components defines data models - tags is how you group the paths https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#openapi-object

type ExternalDoc 

type ExternalDoc struct {
	Description string `json:"description" yaml:"description"`
	Url         string `json:"url" yaml:"url"`
}

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#externalDocumentationObject 

{
 "description": "Find more info here",
 "url": "https://example.com"
}

type Info 

type Info struct {
	Title          string   `json:"title" yaml:"title"`
	Description    string   `json:"description" yaml:"description"`
	TermsOfService string   `json:"termsOfService" yaml:"termsOfService"`
	Contact        *Contact `json:"contact,omitempty" yaml:"contact,omitempty"`
	License        *License `json:"license,omitempty" yaml:"license,omitempty"`
	Version        string   `json:"version" yaml:"version"`
}

Info is meta about the API, following fields are required - title - version https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#info-object 

{
 "title": "Sample Pet Store App",
 "description": "This is a sample server for a pet store.",
 "termsOfService": "http://example.com/terms/",
 "contact": {
   "name": "API Support",
   "url": "http://www.example.com/support",
   "email": "support@example.com"
 },
 "license": {
   "name": "Apache 2.0",
   "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
 },
 "version": "1.0.1"
}

type License 

type License struct {
	Name string `json:"name" yaml:"name"`
	Url  string `json:"url" yaml:"url"`
}

License is license of the exposed API TODO: I don't know there are license for web API, is implementing a service using API violation of API license? https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#licenseObject 

{
 "name": "Apache 2.0",
 "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
}

type MediaType 

type MediaType struct {
	Schema *SchemaOrRef `json:"schema" yaml:"schema"`
}

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#mediaTypeObject

type Operation 

type Operation struct {
	Tags         []string            `json:"tags" yaml:"tags"`
	Summary      string              `json:"summary" yaml:"summary"`
	Description  string              `json:"description" yaml:"description"`
	ExternalDocs *ExternalDoc        `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	OperationId  string              `json:"operationId" yaml:"operationId"`
	Parameters   []Parameter         `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	RequestBody  *RequestBody        `json:"requestBody,omitempty" yaml:"requestBody,omitempty"`
	Responses    map[string]Response `json:"responses" yaml:"responses"`
	// TODO: callbacks
	Deprecated bool      `json:"deprecated" yaml:"deprecated"`
	Security   *Security `json:"security,omitempty" yaml:"security,omitempty"`
	Servers    []Server  `json:"servers,omitempty" yaml:"servers,omitempty"`
}

Operations describes a single API call <HTTP verb> <path>, i.e. GET /pets https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operation-object

type Parameter 

type Parameter struct {
	Name            string       `json:"name" yaml:"name"`
	In              string       `json:"in" yaml:"in"`
	Description     string       `json:"description" yaml:"description"`
	Schema          *SchemaOrRef `json:"schema" yaml:"schema"`
	Style           string       `json:"style" yaml:"style"`
	Required        bool         `json:"required" yaml:"required"`
	Deprecated      bool         `json:"deprecated" yaml:"deprecated"`
	AllowEmptyValue bool         `json:"allowEmptyValue" yaml:"allowEmptyValue"`
}

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameter-object 

{
 "name": "token",
 "in": "header",
 "description": "token to be passed as a header",
 "required": true,
 "schema": {
   "type": "array",
   "items": {
     "type": "integer",
     "format": "int64"
   }
 },
 "style": "simple"
}

type ParameterOrRef 

type ParameterOrRef struct {
	Ref       Reference
	Parameter Parameter
}

func (ParameterOrRef) MarshalJSON 

func (r ParameterOrRef) MarshalJSON() ([]byte, error)

type Path 

type Path struct {
	// TODO: how to deal with Ref, we could inline everything when generate though ....
	//Ref         string      `json:"$ref" yaml:"$ref"`
	Summary     string      `json:"summary" yaml:"summary"`
	Description string      `json:"description" yaml:"description"`
	Servers     []Server    `json:"servers,omitempty" yaml:"servers,omitempty"`
	Parameters  []Parameter `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	Get         *Operation  `json:"get,omitempty" yaml:"get,omitempty"`
	Put         *Operation  `json:"put,omitempty" yaml:"put,omitempty"`
	Post        *Operation  `json:"post,omitempty" yaml:"post,omitempty"`
	Delete      *Operation  `json:"delete,omitempty" yaml:"delete,omitempty"`
	Options     *Operation  `json:"options,omitempty" yaml:"options,omitempty"`
	Head        *Operation  `json:"head,omitempty" yaml:"head,omitempty"`
	Patch       *Operation  `json:"patch,omitempty" yaml:"patch,omitempty"`
	Trace       *Operation  `json:"trace,omitempty" yaml:"trace,omitempty"`
}

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#path-item-object

type Reference 

type Reference struct {
	Ref string `json:"$ref" yaml:"$ref"`
}

Reference is used to references models defined in current API doc and external doc https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#referenceObject 

{
	"$ref": "#/components/schemas/Pet"
}

type RequestBody 

type RequestBody struct {
	Description string               `json:"description" yaml:"description"`
	Content     map[string]MediaType `json:"content" yaml:"content"`
	Required    bool                 `json:"required" yaml:"required"`
}

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#requestBodyObject

type RequestBodyOrRef 

type RequestBodyOrRef struct {
	Ref         Reference
	RequestBody RequestBody
}

func (RequestBodyOrRef) MarshalJSON 

func (r RequestBodyOrRef) MarshalJSON() ([]byte, error)

type Response 

type Response struct {
	Description string `json:"description" yaml:"description"`
	// TODO: headers, need to define header object https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#headerObject
	// TODO: might need to use pointer to indicate there is no response body
	Content map[string]MediaType `json:"content" yaml:"content"`
}

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responseObject

type ResponseOrRef 

type ResponseOrRef struct {
	Ref      Reference
	Response Response
}

func (ResponseOrRef) MarshalJSON 

func (r ResponseOrRef) MarshalJSON() ([]byte, error)

type Schema 

type Schema struct {
	Title       string `json:"title,omitempty" yaml:"title,omitempty"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	Type   string `json:"type" yaml:"type"`
	Format string `json:"format,omitempty" yaml:"format,omitempty"`

	// object
	Properties map[string]*SchemaOrRef `json:"properties,omitempty" yaml:"properties,omitempty"`
	Required   []string                `json:"required,omitempty" yaml:"required,omitempty"`

	// array
	// TODO: items can even be a slice of schema ... tuple is allowed?
	// NOTE: use pointer to avoid `invalid recursive type Schema`
	// https://stackoverflow.com/questions/8261058/invalid-recursive-type-in-a-struct-in-go
	Items *SchemaOrRef `json:"items,omitempty" yaml:"items,omitempty"` // NOTE: it need

}

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schema-object TODO: only a small subset is included, should be enough to describe api without validation throw people to json schema doc makes the hard part in open api pretty easy for the writer TODO: ref https://github.com/googleapis/gnostic/blob/master/jsonschema/models.go

type SchemaOrRef 

type SchemaOrRef struct {
	Ref    Reference
	Schema Schema
}

func (*SchemaOrRef) MarshalJSON 

func (r *SchemaOrRef) MarshalJSON() ([]byte, error)

MarshalJSON use reference if provided, otherwise it encode the inline schema it implements https://golang.org/pkg/encoding/json/#Marshaler interface

func (*SchemaOrRef) MarshalYAML 

func (r *SchemaOrRef) MarshalYAML() (interface{}, error)

it implements https://godoc.org/gopkg.in/yaml.v2#Marshaler interface

type Security 

type Security struct {
}

TODO: security

type Server 

type Server struct {
	Url         string `json:"url" yaml:"url"`
	Description string `json:"description" yaml:"description"`
}

Server is endpoint of a remote server that can be used to test the API, it can be put into multi levels of the doc and the inner level overrides the outer levels https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#serverObject 

{
 "servers": [
   {
     "url": "https://development.gigantic-server.com/v1",
     "description": "Development server"
   },
   {
     "url": "https://staging.gigantic-server.com/v1",
     "description": "Staging server"
   },
   {
     "url": "https://api.gigantic-server.com/v1",
     "description": "Production server"
   }
 ]
}

type Tag 

type Tag struct {
	Name         string       `json:"name" yaml:"name"`
	Description  string       `json:"description" yaml:"description"`
	ExternalDocs *ExternalDoc `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
}

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#tagObject 

{
	"name": "pet",
	"description": "Pets operations"
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.