Generating spec from code

[ppipada]

Hi,

Do you support generating spec from code? I see parsing, validation, etc but not sure if code to spec is supported here.

Thanks

[daveshanley]

Hi,

Do you mean this? https://pb33f.io/libopenapi/modifying/

[daveshanley]

Or more specifically, this: https://pb33f.io/libopenapi/modifying/#creating-new-openapi-specifications

[ppipada]

Thanks for your response @daveshanley

I am not looking for the above. General usecase is similar to the one that goswagger supports here: https://goswagger.io/generate/spec.html (doesnt support openapi 3, 3.1 and json schema)

Basically: annotate actual go structs with some comments or tags (like jsonschema tags) and get a schema doc (yaml or json) out, then use that schema doc using the libraries in this repo to validate and decode incoming requests to the same structs. This way source of truth remains go code only and openapi serves as a IDL and consistent contract definition.

[daveshanley]

libopenapi does not have that capability yet, unfortunately. I'd like to learn more about what you would love to see implemented as a feature set. Could you give me examples of the annotations/comments you would like to see? How would you like the library to operate?

[ppipada]

Thanks for the response.
If you feel that such a feature can be part of this package, I can give the code a shot (will refer goswagger, jsonschema-go as needed).
Adding my thoughts below.

Goal of the feature

• Make code the source of truth for openapi schema info, use it to generate schema doc, which can be used to perform the functionality already present in this great lib.

Functionality invocation

• Do command line or go generate with proper options to get a schema doc. E.g:
• openapicmd generate -o openapi.yaml OR //go:generate openapicmd generate -o openapi.yaml

Annotations

API metadata

Add openapi schema level metadata as a top level comment in a doc.go or main.go file. E.g: Similar to what is provided here, but compatible with openapi 3.x

Annotation: openapi:meta

// openapi:meta
// Package MyPet Rest Server
//
//
//	Schemes: https
//	Host: localhost
//	BasePath: /pet/v1
//	Version: 1.0.0
//
//	Consumes:
//	- application/json
//
//	Produces:
//	- application/json

Operation info

Add a comment at the interface implementing the operation or the path string literal. Can add adhoc things as required in yaml format E.g: Similar to what is provided here, but compatible with openapi 3.x

Annotation: openapi:operation [method] [path pattern] [?tag1 tag2 tag3] [operation id]

// openapi:operation Put /pets/{name} getPet
//
// Add a pet to the system
//
// Could be any pet
//
// ---
// produces:
// - application/json

Request info (params, queries, headers, json schema tags).

Annotate the struct which will hold the constants for the request params accordingly. The struct comment can hold the operation id comment and the struct itself can hold further details

Annotation: openapi:request [operation id1 operation id 2]

// openapi:request getPet
type GetPetRequest struct {
   Name string `in:"path" path:"name" example:"hoppy" pattern:"^[a-z][A-Z]" required:true`
   
   Info PetInfo `in:"body" required:true` 
}

// openapi:model
type PetInfo struct {
  Type string `json:type enum:"dog,cat"`
}

Response info

Annotate response struct as model

Annotation: openapi:model [operation id1 operation id 2]

 // openapi:model
type PetInfo struct {
  Type string `json:type`
}