Skip to content

Commit 5fad90c

Browse files
guohuangguohuang
committed
issue#2359: added README document generation for Go
1 parent 4f84c7d commit 5fad90c

File tree

14 files changed

+912
-0
lines changed

14 files changed

+912
-0
lines changed

‎modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/GoClientCodegen.java‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ public class GoClientCodegen extends DefaultCodegen implements CodegenConfig {
1919

2020
protected String packageName = "swagger";
2121
protected String packageVersion = "1.0.0";
22+
protected String apiDocPath = "docs/";
23+
protected String modelDocPath = "docs/";
2224

2325
public CodegenType getTag() {
2426
return CodegenType.CLIENT;
@@ -37,6 +39,10 @@ public GoClientCodegen() {
3739
outputFolder = "generated-code/go";
3840
modelTemplateFiles.put("model.mustache", ".go");
3941
apiTemplateFiles.put("api.mustache", ".go");
42+
43+
modelDocTemplateFiles.put("model_doc.mustache", ".md");
44+
apiDocTemplateFiles.put("api_doc.mustache", ".md");
45+
4046
templateDir = "go";
4147

4248
setReservedWordsLowerCase(
@@ -126,6 +132,9 @@ public void processOpts() {
126132

127133
additionalProperties.put(CodegenConstants.PACKAGE_NAME, packageName);
128134
additionalProperties.put(CodegenConstants.PACKAGE_VERSION, packageVersion);
135+
136+
additionalProperties.put("apiDocPath", apiDocPath);
137+
additionalProperties.put("modelDocPath", modelDocPath);
129138

130139
modelPackage = packageName;
131140
apiPackage = packageName;
@@ -262,6 +271,30 @@ public void postProcessParameter(CodegenParameter parameter){
262271
}
263272

264273

274+
@Override
275+
public String apiDocFileFolder() {
276+
return (outputFolder + "/" + apiDocPath).replace('/', File.separatorChar);
277+
}
278+
279+
@Override
280+
public String modelDocFileFolder() {
281+
return (outputFolder + "/" + modelDocPath).replace('/', File.separatorChar);
282+
}
283+
284+
@Override
285+
public String toModelDocFilename(String name) {
286+
//unable to use model file name because the mustache template does not have the model file name variable (python has the same issue)
287+
//return toModelFilename(name);
288+
return toModelName(name);
289+
}
290+
291+
@Override
292+
public String toApiDocFilename(String name) {
293+
//unable to use api file name because the mustache template does not have the api file name variable
294+
//return toApiFilename(name);
295+
return toApiName(name);
296+
}
297+
265298
@Override
266299
public String getTypeDeclaration(Property p) {
267300
if(p instanceof ArrayProperty) {

‎modules/swagger-codegen/src/main/resources/go/README.mustache‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,63 @@
11
# Go API client for {{packageName}}
22

3+
{{#appDescription}}
4+
{{{appDescription}}}
5+
{{/appDescription}}
6+
37
## Overview
48
This API client was generated by the [swagger-codegen](https://github.com/swagger-api/swagger-codegen) project. By using the [swagger-spec](https://github.com/swagger-api/swagger-spec) from a remote server, you can easily generate an API client.
59

10+
- API version: {{appVersion}}
11+
- Package version: {{artifactVersion}}
12+
- Build date: {{generatedDate}}
13+
- Build package: {{generatorClass}}
14+
{{#infoUrl}}
15+
For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
16+
{{/infoUrl}}
617

718
## Installation
819
Put the package under your project folder and add the following in import:
920
```
1021
"./{{packageName}}"
1122
```
1223

24+
## Documentation for API Endpoints
25+
26+
All URIs are relative to *{{basePath}}*
27+
28+
Class | Method | HTTP request | Description
29+
------------ | ------------- | ------------- | -------------
30+
{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
31+
{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
32+
33+
## Documentation For Models
34+
35+
{{#models}}{{#model}} - [{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
36+
{{/model}}{{/models}}
37+
38+
## Documentation For Authorization
39+
40+
{{^authMethods}} All endpoints do not require authorization.
41+
{{/authMethods}}{{#authMethods}}{{#last}} Authentication schemes defined for the API:{{/last}}{{/authMethods}}
42+
{{#authMethods}}## {{{name}}}
43+
44+
{{#isApiKey}}- **Type**: API key
45+
- **API key parameter name**: {{{keyParamName}}}
46+
- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
47+
{{/isApiKey}}
48+
{{#isBasic}}- **Type**: HTTP basic authentication
49+
{{/isBasic}}
50+
{{#isOAuth}}- **Type**: OAuth
51+
- **Flow**: {{{flow}}}
52+
- **Authorizatoin URL**: {{{authorizationUrl}}}
53+
- **Scopes**: {{^scopes}}N/A{{/scopes}}
54+
{{#scopes}} - **{{{scope}}}**: {{{description}}}
55+
{{/scopes}}
56+
{{/isOAuth}}
57+
58+
{{/authMethods}}
59+
60+
## Author
61+
62+
{{#apiInfo}}{{#apis}}{{^hasMore}}{{infoEmail}}
63+
{{/hasMore}}{{/apis}}{{/apiInfo}}

‎modules/swagger-codegen/src/main/resources/go/api_doc.mustache‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# {{invokerPackage}}\{{classname}}{{#description}}
2+
{{description}}{{/description}}
3+
4+
All URIs are relative to *{{basePath}}*
5+
6+
Method | HTTP request | Description
7+
------------- | ------------- | -------------
8+
{{#operations}}{{#operation}}[**{{operationId}}**]({{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
9+
{{/operation}}{{/operations}}
10+
11+
{{#operations}}
12+
{{#operation}}
13+
# **{{{operationId}}}**
14+
> {{#returnType}}{{{returnType}}} {{/returnType}}{{{operationId}}}({{#allParams}}${{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}})
15+
16+
{{{summary}}}{{#notes}}
17+
18+
{{{notes}}}{{/notes}}
19+
20+
21+
### Parameters
22+
{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}}
23+
Name | Type | Description | Notes
24+
------------- | ------------- | ------------- | -------------{{/-last}}{{/allParams}}
25+
{{#allParams}} **{{paramName}}** | {{#isFile}}**{{dataType}}**{{/isFile}}{{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{^isFile}}[**{{dataType}}**]({{baseType}}.md){{/isFile}}{{/isPrimitiveType}}| {{description}} | {{^required}}[optional] {{/required}}{{#defaultValue}}[default to {{defaultValue}}]{{/defaultValue}}
26+
{{/allParams}}
27+
28+
### Return type
29+
30+
{{#returnType}}{{#returnTypeIsPrimitive}}**{{{returnType}}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}[**{{{returnType}}}**]({{returnBaseType}}.md){{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}void (empty response body){{/returnType}}
31+
32+
### Authorization
33+
34+
{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{{name}}}](../README.md#{{{name}}}){{^-last}}, {{/-last}}{{/authMethods}}
35+
36+
### HTTP reuqest headers
37+
38+
- **Content-Type**: {{#consumes}}{{mediaType}}{{#hasMore}}, {{/hasMore}}{{/consumes}}{{^consumes}}Not defined{{/consumes}}
39+
- **Accept**: {{#produces}}{{mediaType}}{{#hasMore}}, {{/hasMore}}{{/produces}}{{^produces}}Not defined{{/produces}}
40+
41+
[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
42+
43+
{{/operation}}
44+
{{/operations}}

‎modules/swagger-codegen/src/main/resources/go/model_doc.mustache‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{{#models}}{{#model}}# {{classname}}
2+
3+
## Properties
4+
Name | Type | Description | Notes
5+
------------ | ------------- | ------------- | -------------
6+
{{#vars}}**{{name}}** | {{#isPrimitiveType}}**{{datatype}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{datatype}}**]({{complexType}}.md){{/isPrimitiveType}} | {{description}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}}
7+
{{/vars}}
8+
9+
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
10+
11+
{{/model}}{{/models}}

‎samples/client/petstore/go/README.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,79 @@
11
# Go API client for swagger
22

3+
This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.
4+
35
## Overview
46
This API client was generated by the [swagger-codegen](https://github.com/swagger-api/swagger-codegen) project. By using the [swagger-spec](https://github.com/swagger-api/swagger-spec) from a remote server, you can easily generate an API client.
57

8+
- API version: 1.0.0
9+
- Package version:
10+
- Build date: 2016-04-14T14:05:06.510-07:00
11+
- Build package: class io.swagger.codegen.languages.GoClientCodegen
612

713
## Installation
814
Put the package under your project folder and add the following in import:
915
```
1016
"./swagger"
1117
```
1218

19+
## Documentation for API Endpoints
20+
21+
All URIs are relative to *http://petstore.swagger.io/v2*
22+
23+
Class | Method | HTTP request | Description
24+
------------ | ------------- | ------------- | -------------
25+
*PetApi* | [**AddPet**](docs/PetApi.md#addpet) | **Post** /pet | Add a new pet to the store
26+
*PetApi* | [**DeletePet**](docs/PetApi.md#deletepet) | **Delete** /pet/{petId} | Deletes a pet
27+
*PetApi* | [**FindPetsByStatus**](docs/PetApi.md#findpetsbystatus) | **Get** /pet/findByStatus | Finds Pets by status
28+
*PetApi* | [**FindPetsByTags**](docs/PetApi.md#findpetsbytags) | **Get** /pet/findByTags | Finds Pets by tags
29+
*PetApi* | [**GetPetById**](docs/PetApi.md#getpetbyid) | **Get** /pet/{petId} | Find pet by ID
30+
*PetApi* | [**UpdatePet**](docs/PetApi.md#updatepet) | **Put** /pet | Update an existing pet
31+
*PetApi* | [**UpdatePetWithForm**](docs/PetApi.md#updatepetwithform) | **Post** /pet/{petId} | Updates a pet in the store with form data
32+
*PetApi* | [**UploadFile**](docs/PetApi.md#uploadfile) | **Post** /pet/{petId}/uploadImage | uploads an image
33+
*StoreApi* | [**DeleteOrder**](docs/StoreApi.md#deleteorder) | **Delete** /store/order/{orderId} | Delete purchase order by ID
34+
*StoreApi* | [**GetInventory**](docs/StoreApi.md#getinventory) | **Get** /store/inventory | Returns pet inventories by status
35+
*StoreApi* | [**GetOrderById**](docs/StoreApi.md#getorderbyid) | **Get** /store/order/{orderId} | Find purchase order by ID
36+
*StoreApi* | [**PlaceOrder**](docs/StoreApi.md#placeorder) | **Post** /store/order | Place an order for a pet
37+
*UserApi* | [**CreateUser**](docs/UserApi.md#createuser) | **Post** /user | Create user
38+
*UserApi* | [**CreateUsersWithArrayInput**](docs/UserApi.md#createuserswitharrayinput) | **Post** /user/createWithArray | Creates list of users with given input array
39+
*UserApi* | [**CreateUsersWithListInput**](docs/UserApi.md#createuserswithlistinput) | **Post** /user/createWithList | Creates list of users with given input array
40+
*UserApi* | [**DeleteUser**](docs/UserApi.md#deleteuser) | **Delete** /user/{username} | Delete user
41+
*UserApi* | [**GetUserByName**](docs/UserApi.md#getuserbyname) | **Get** /user/{username} | Get user by user name
42+
*UserApi* | [**LoginUser**](docs/UserApi.md#loginuser) | **Get** /user/login | Logs user into the system
43+
*UserApi* | [**LogoutUser**](docs/UserApi.md#logoutuser) | **Get** /user/logout | Logs out current logged in user session
44+
*UserApi* | [**UpdateUser**](docs/UserApi.md#updateuser) | **Put** /user/{username} | Updated user
45+
46+
47+
## Documentation For Models
48+
49+
- [ApiResponse](docs/ApiResponse.md)
50+
- [Category](docs/Category.md)
51+
- [Order](docs/Order.md)
52+
- [Pet](docs/Pet.md)
53+
- [Tag](docs/Tag.md)
54+
- [User](docs/User.md)
55+
56+
57+
## Documentation For Authorization
58+
59+
60+
## petstore_auth
61+
62+
- **Type**: OAuth
63+
- **Flow**: implicit
64+
- **Authorizatoin URL**: http://petstore.swagger.io/api/oauth/dialog
65+
- **Scopes**:
66+
- **write:pets**: modify pets in your account
67+
- **read:pets**: read your pets
68+
69+
## api_key
70+
71+
- **Type**: API key
72+
- **API key parameter name**: api_key
73+
- **Location**: HTTP header
74+
75+
76+
## Author
77+
78+
[email protected]
79+

‎samples/client/petstore/go/docs/ApiResponse.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# ApiResponse
2+
3+
## Properties
4+
Name | Type | Description | Notes
5+
------------ | ------------- | ------------- | -------------
6+
**Code** | **int32** | | [optional] [default to null]
7+
**Type_** | **string** | | [optional] [default to null]
8+
**Message** | **string** | | [optional] [default to null]
9+
10+
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
11+
12+

‎samples/client/petstore/go/docs/Category.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Category
2+
3+
## Properties
4+
Name | Type | Description | Notes
5+
------------ | ------------- | ------------- | -------------
6+
**Id** | **int64** | | [optional] [default to null]
7+
**Name** | **string** | | [optional] [default to null]
8+
9+
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
10+
11+

‎samples/client/petstore/go/docs/Order.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Order
2+
3+
## Properties
4+
Name | Type | Description | Notes
5+
------------ | ------------- | ------------- | -------------
6+
**Id** | **int64** | | [optional] [default to null]
7+
**PetId** | **int64** | | [optional] [default to null]
8+
**Quantity** | **int32** | | [optional] [default to null]
9+
**ShipDate** | [**time.Time**](time.Time.md) | | [optional] [default to null]
10+
**Status** | **string** | Order Status | [optional] [default to null]
11+
**Complete** | **bool** | | [optional] [default to null]
12+
13+
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
14+
15+

‎samples/client/petstore/go/docs/Pet.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Pet
2+
3+
## Properties
4+
Name | Type | Description | Notes
5+
------------ | ------------- | ------------- | -------------
6+
**Id** | **int64** | | [optional] [default to null]
7+
**Category** | [**Category**](Category.md) | | [optional] [default to null]
8+
**Name** | **string** | | [default to null]
9+
**PhotoUrls** | **[]string** | | [default to null]
10+
**Tags** | [**[]Tag**](Tag.md) | | [optional] [default to null]
11+
**Status** | **string** | pet status in the store | [optional] [default to null]
12+
13+
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
14+
15+

0 commit comments

Comments
 (0)