Adding basic support for XML structure #328
Conversation
openapi.go
Outdated
| if ok { | ||
| xmlTagName := strings.Split(xmlTag, ",")[0] // remove omitempty, etc | ||
| // if xml tag name is "-", don't add it to the schema | ||
| if xmlTagName != "-" { |
There was a problem hiding this comment.
Instead of nesting more if can just do
if xmlTagName == "-" {
continue
}
There was a problem hiding this comment.
If we use continue, all subsequent code (such as handling examples, validation, and descriptions) will be skipped if the field isn't included in XML.
In this section, only XML-related information is processed.
There was a problem hiding this comment.
I believe we would then need to change the JSON check above to handle the same case. I.E when the xml tag is provided but not the json tag.
There was a problem hiding this comment.
Also I think it would make it a bit cleaner to perform both these actions in helpers so we can early return.
We also will need to handle the case where both the xml and json tags are - we wouldn't want the description, examples, or validation processed. Kinda like how we do already with the continue in the json check for -. Would probably be worth to check that early for both so we can continue early.
| IngressDate string `json:"in_date" xml:"date,attr"` | ||
| } | ||
|
|
||
| type MyOutputStructWithXmlAttribute struct { |
There was a problem hiding this comment.
I think we should add a test for a struct with just xml attributes. As well as one with json:"-"
openapi.go
Outdated
| // We support the following xml tags: | ||
| // - "xml" field tag: specifies the XML element name | ||
| // - "xml=attr" field tag: specifies that the field is an XML attribute | ||
| // - "xml=wrapped" field tag: specifies that the field is wrapped in an XML element | ||
| xmlField := field.Tag.Get("xml") | ||
| // if xml tag name is "-", don't add it to the schema | ||
| if xmlField != "-" && xmlField != "" { | ||
| xmlFieldName := strings.Split(xmlField, ",")[0] // remove omitempty, etc | ||
|
|
||
| if xmlFieldName == "" { | ||
| xmlFieldName = field.Name | ||
| } | ||
|
|
||
| propertyValue.XML = &openapi3.XML{ | ||
| Name: xmlFieldName, | ||
| } | ||
|
|
||
| xmlFields := strings.Split(xmlField, ",") | ||
| if slices.Contains(xmlFields, "attr") { | ||
| propertyValue.XML.Attribute = true | ||
| } | ||
| if slices.Contains(xmlFields, "wrapped") { | ||
| propertyValue.XML.Wrapped = true | ||
| } | ||
| } |
There was a problem hiding this comment.
I would move this in a dedicated method, and also move the code related to json tag parsing to its own method too.
Because now the code is too complex.
Also it would allow you to return with early return when needed. It would avoid imbricated if levels
There was a problem hiding this comment.
@ccoVeille
Refactor OpenAPI Metadata Parsing and Introduce MetadataParsers
-
Added a new file,
openapi_metadata.go(and test file), which includes:MetadataParsers: A struct to define functions responsible for constructing the OpenAPI specification and the order in which they are executed.- Modular methods for constructing the OpenAPI specification, extracted from
parseStructTags:ExampleMetadataParserValidationMetadataParserDescriptionMetadataParserXMLMetadataParserJSONMetadataParser
-
Modified
openapi.go:- Removed the
parseStructTagsfunction. - Introduced initialization for
MetadataParsersto manage the parsing logic in a structured and extensible way.
- Removed the
This ensures better control in cases where different methods may update the same value in the OpenAPI specification.
Co-authored-by: ccoVeille <3875889+ccoVeille@users.noreply.github.com>
… add customizable processing order using new struct MetadataParsers
There was a problem hiding this comment.
I don't think you need the openapi_ prefix for this file, everything is about openapi.
Also metadata is not clear enough for a file name I think (with or without the openapi_prefix)
Maybe metadata parser of something like that.
Naming is hard
| func (mp *MetadataParsers) insertAtStart(entry MetadataParserEntry) { | ||
| mp.registeredParsers = append([]MetadataParserEntry{entry}, mp.registeredParsers...) | ||
| } | ||
|
|
||
| func (mp *MetadataParsers) insertAtEnd(entry MetadataParserEntry) { | ||
| mp.registeredParsers = append(mp.registeredParsers, entry) | ||
| } |
There was a problem hiding this comment.
Append and prepend are more commonly used than insert at start/end
| if !validPositions[position] { | ||
| return fmt.Errorf("Invalid position. Use 'start', 'end', 'before', or 'after'") | ||
| } | ||
| if (position == "before" || position == "after") && mp.findParserIndex(relativeTo) == -1 { |
There was a problem hiding this comment.
Before, after, end, start should be constants prefixed with position or something
| {Name: "exampleParser", Parser: ExampleMetadataParser}, | ||
| {Name: "validationParser", Parser: ValidationMetadataParser}, | ||
| {Name: "descriptionParser", Parser: DescriptionMetadataParser}, | ||
| {Name: "XMLParser", Parser: XMLMetadataParser}, | ||
| {Name: "JSONParser", Parser: JSONMetadataParser}, |
There was a problem hiding this comment.
Shouldn't these names be constants prefixed with metadataParser
This pull request introduces basic support for XML tags in OpenAPI documentation, allowing the following features to be defined for schema fields:
The
xml:"customName"struct tag allows specifying a custom name for the XML element.The
xml:"name,attr"struct tag marks a field as an XML attribute.The
xml:"name,wrapped"struct tag enables support for wrapping elements (e.g.,<items><item>...</item></items>).