From 73f20c92440e0b0d4405e06d4cf30f3f51c899c2 Mon Sep 17 00:00:00 2001 From: Karel Bilek Date: Wed, 15 Sep 2021 22:22:37 +0700 Subject: [PATCH] Add option for hidden enum --- .gitignore | 1 + parser/parser.go | 13 +- test/testdata/scripts/hidden_enum.txt | 187 ++++++++++++++++++++++++++ 3 files changed, 196 insertions(+), 5 deletions(-) create mode 100644 test/testdata/scripts/hidden_enum.txt diff --git a/.gitignore b/.gitignore index 34a0dbc..4ca1494 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ docgen .DS_Store +.idea diff --git a/parser/parser.go b/parser/parser.go index 13e68a9..c41a1fd 100644 --- a/parser/parser.go +++ b/parser/parser.go @@ -34,6 +34,8 @@ const ( OnlyExternalEnabled ) +const hidingIndicator = "docgen: hide" + // ParseFile parses a proto file. func ParseFile(file *FileDescWrapper, onlyExternal OnlyExternalOpt) (*File, error) { pkgName := file.GetPackage() @@ -165,10 +167,12 @@ func parseValues( comment := comments[p] comment = nonNilComment(comment) comment.Leading = strings.TrimPrefix(comment.Leading, typeName+"_") - res = append(res, &Value{ - Name: v.GetName(), - Comment: comment, - }) + if !strings.Contains(comment.Leading, hidingIndicator) { + res = append(res, &Value{ + Name: v.GetName(), + Comment: comment, + }) + } } } return res @@ -458,7 +462,6 @@ func generateResponseExample(messages map[string]*Message, name string) (string, // normalizeRequestFields is used to filter out all fields marked with an predefined indicator of a request message. func normalizeRequestFields(messages map[string]*Message) { - const hidingIndicator = "docgen: hide" for _, message := range messages { var filtered []*Field for _, f := range message.Fields { diff --git a/test/testdata/scripts/hidden_enum.txt b/test/testdata/scripts/hidden_enum.txt new file mode 100644 index 0000000..8e5278a --- /dev/null +++ b/test/testdata/scripts/hidden_enum.txt @@ -0,0 +1,187 @@ +# note that Account's MajorType is in a different package "types", +# but still generated in the transactions/all.md annex +# (and also types/types.md, but we don't check that here) +exec gunk generate ./... +cmp transactions/all.md transactions/all.md.golden + +-- .gunkconfig -- +[generate] +command=docgen +-- types/types.gunk -- +package types + +// MajorType describes the type of the account. +type MajorType int + +const ( + // docgen: hide + UnknownMajorType MajorType = iota + // Checking account. + Checking + // Saving account. + Saving + // TimeDeposit for a time deposit account. + TimeDeposit + // CommercialLoan for a business loan account. + CommercialLoan + // MortgageLoan for a home loan account. + MortgageLoan + // ConsumerLoan for a consumer loan account. + ConsumerLoan + // EvilLoan is evil. docgen: hide + EvilLoan +) + +-- transactions/transactions.gunk -- +// +gunk openapiv2.Swagger{ +// Swagger: "2.0", +// Info: openapiv2.Info{ +// Title: "Transactions API", +// Description: "Provides create and read operations on the transaction resource.", +// Version: "1.0.0", +// }, +// Host: "openbank.com", +// BasePath: "/path", +// Schemes: []openapiv2.Scheme{ +// openapiv2.HTTPS, +// }, +// } +package transactions + +import ( + "github.com/gunk/opt/http" + "github.com/gunk/opt/openapiv2" + + types "testdata.tld/util/types" +) + +// Transaction defines a transaction. +type Transaction struct { + // To is the account to credit. + To Account `pb:"1" json:"to"` + + // From is the account to debit. + From Account `pb:"2" json:"from"` +} + +// Account represents an account. +type Account struct { + // Number is the account number. + Number string `pb:"1" json:"number"` + + // MajorType is the type of account. + MajorType types.MajorType `pb:"2" json:"major_type"` +} + +// GetTransactionRequest is the request envelope to get an transaction by its identifier. +type GetTransactionRequest struct { + // TransactionID is the unique identifier of a transaction. + TransactionID string `pb:"1" json:"transaction_id"` +} + +// TransactionService provides transaction-related operations. +type TransactionService interface { + // GetTransaction retrieves the details of a transaction. + // + // +gunk http.Match{ + // Method: "GET", + // Path: "/v1/transactions/{TransactionID}", + // } + // +gunk openapiv2.Operation{ + // Tags: []string{"Transaction"}, + // Description: "Retrieves all data from a transaction, selected by the `transaction_id` you supplied.", + // Summary: "Retrieve a transaction", + // Responses: map[string]openapiv2.Response{ + // "200": openapiv2.Response{ + // Description: "Request executed successfully.", + // }, + // "404": openapiv2.Response{ + // Description: "Returned when the resource is not found.", + // }, + // }, + // } + GetTransaction(GetTransactionRequest) Transaction +} +-- transactions/all.md.golden -- +# Transactions API v1.0.0 + +Provides create and read operations on the transaction resource. + +* Host `https://openbank.com` + +* Base Path `/path` + +## Retrieve a transaction + +Retrieves all data from a transaction, selected by the `transaction_id` you supplied. + +```sh +curl -X GET \ + https://openbank.com/path/v1/transactions/{TransactionID} \ + -H 'x-api-key: USE_YOUR_API_KEY' +``` + +### HTTP Request + +`GET https://openbank.com/path/v1/transactions/{TransactionID}` + +### Query Parameters + +| Name | Type | Description | +|----------------|--------|----------------------------------------------------------| +| transaction_id | string | TransactionID is the unique identifier of a transaction. | + +### Responses + +#### Response body + +| Name | Type | Description | +|------|---------|-------------------------------| +| to | Account | To is the account to credit. | +| from | Account | From is the account to debit. | + +##### Objects + +###### Account + +| Name | Type | Description | +|------------|-----------|-----------------------------------| +| number | string | Number is the account number. | +| major_type | MajorType | MajorType is the type of account. | + +##### Enums + +###### MajorType + +MajorType describes the type of the account. + +| Value | Description | +|----------------|---------------------------------------------| +| Checking | Checking account. | +| Saving | Saving account. | +| TimeDeposit | TimeDeposit for a time deposit account. | +| CommercialLoan | CommercialLoan for a business loan account. | +| MortgageLoan | MortgageLoan for a home loan account. | +| ConsumerLoan | ConsumerLoan for a consumer loan account. | + +Example: + +```json +{ + "to": { + "number": "string", + "major_type": "MajorType" + }, + "from": { + "number": "string", + "major_type": "MajorType" + } +} +``` + +#### Response codes + +| Status | Description | +|--------|------------------------------------------| +| 200 | Request executed successfully. | +| 404 | Returned when the resource is not found. | \ No newline at end of file