Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

API: GetSchemaType/GetSchemaTypeMapping export the overall informations about property doc, default value, readonly, ... #625

Closed
amyXia1994 opened this issue Jul 26, 2023 · 4 comments · Fixed by #633
Assignees

Comments

@amyXia1994
Copy link
Contributor

The GetSchemaType and GetSchemaTypeMapping API now export schema Type in following structure:

message KclType {
	string type = 1;                     // schema, dict, list, str, int, float, bool, null, type_string
	repeated KclType union_types = 2 ;   // union types
	string default = 3;                  // default value

	string schema_name = 4;              // schema name
	string schema_doc = 5;               // schema doc
	map<string, KclType> properties = 6; // schema properties
	repeated string required = 7;        // required schema properties, [property_name1, property_name2]

	KclType key = 8;                     // dict key type
	KclType item = 9;                    // dict/list item type

	int32 line = 10;

	repeated Decorator decorators = 11;  // schema decorators
}

Following information of the schema are not covered:

  1. the description of each property
  2. the examples of the schema
  3. the file path of the schema

see schema object in openapi: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schema-object

@amyXia1994
Copy link
Contributor Author

@Peefy Peefy assigned amyXia1994 and unassigned amyXia1994 Aug 1, 2023
@Peefy
Copy link
Contributor

Peefy commented Aug 1, 2023

With the implementation of KCL rust doc parser, these field implementations have become feasible and can be added to the API while maintaining compatibility.

@Peefy
Copy link
Contributor

Peefy commented Aug 1, 2023

The new API is here @amyXia1994

message KclType {
	string type = 1;                     // schema, dict, list, str, int, float, bool, null, type_string
	repeated KclType union_types = 2 ;   // union types
	string default = 3;                  // default value
	string schema_name = 4;              // schema name
	string schema_doc = 5;               // schema doc
	map<string, KclType> properties = 6; // schema properties
	repeated string required = 7;        // required schema properties, [property_name1, property_name2]
	KclType key = 8;                     // dict key type
	KclType item = 9;                    // dict/list item type
	int32 line = 10;
	repeated Decorator decorators = 11;  // schema decorators

	string filename = 12;                // filename represents the absolute path of the file name where the attribute is located.
	string pkg_path = 13;                // pkg_path represents the path name of the package where the attribute is located.
	string description = 14;             // description represents the document of the attribute.
	map<string, Example> examples = 15;  // A map object to hold examples, the key is the example name.
}

message Decorator {
	string name = 1;
	repeated string arguments = 2;
	map<string, string> keywords = 3;
}

message Example {
	string summary = 1;                // Short description for the example.
	string description = 2;            // Long description for the example.
	google.protobuf.Any value = 3;     // Embedded literal example.
}

@amyXia1994
Copy link
Contributor Author

amyXia1994 commented Aug 1, 2023

@Peefy good job!

I think the doc for each Property is still missing. The schema_doc field only covers the doc of the property type when the property type is schema, but does not cover the doc of the property. In OpenAPI, if nested models are explicitly declared, a $ref field can be used along with description to allow the schema type to be defined in a deeper level of nesting. ref: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#reference-object I saw you've add the description to message KclType 👍

And I might have missed some other necessary fields in the KclType model in the original issue:

Furthermore, if we support generating docs for other "types" of models, such as mixin, protocol, and rule, This API might need some refactoring. Since the spec of all those models might be different, perhaps a new "KCLType" which wraps all those models is needed?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants