Skip to content

Commit f8842b0

Browse files
ityuhuiityuhui
authored
[C-libcurl] Generate API and module documents automatically (#8981)
1 parent a139230 commit f8842b0

File tree

15 files changed

+913
-5
lines changed

15 files changed

+913
-5
lines changed

‎modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/CLibcurlClientCodegen.java

+2-5
Original file line numberDiff line numberDiff line change
@@ -50,9 +50,6 @@ public class CLibcurlClientCodegen extends DefaultCodegen implements CodegenConf
5050
public CLibcurlClientCodegen() {
5151
super();
5252

53-
// TODO: c maintainer review
54-
// Assumes that C community considers api/model header files as documentation.
55-
// Generator supports Basic, OAuth, and API key explicitly. Bearer is excluded although clients are able to set headers directly.
5653
modifyFeatureSet(features -> features
5754
.includeDocumentationFeatures(
5855
DocumentationFeature.Readme
@@ -82,8 +79,8 @@ public CLibcurlClientCodegen() {
8279
modelTemplateFiles.put("model-body.mustache", ".c");
8380
apiTemplateFiles.put("api-header.mustache", ".h");
8481
apiTemplateFiles.put("api-body.mustache", ".c");
85-
//modelDocTemplateFiles.put("model_doc.mustache", ".md");
86-
//apiDocTemplateFiles.put("api_doc.mustache", ".md");
82+
modelDocTemplateFiles.put("model_doc.mustache", ".md");
83+
apiDocTemplateFiles.put("api_doc.mustache", ".md");
8784
embeddedTemplateDir = templateDir = "C-libcurl";
8885

8986
// TODO add auto-generated test files

‎modules/openapi-generator/src/main/resources/C-libcurl/README.md.mustache

+49
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,55 @@ Once compiled, you can run it with ``` ./main ```
6464

6565
Note: You don't need to specify includes for models and include folder seperately as they are path linked. You just have to import the api.h file in your code, the include linking will work.
6666

67+
## Documentation for API Endpoints
68+
69+
All URIs are relative to *{{basePath}}*
70+
71+
Category | Method | HTTP request | Description
72+
------------ | ------------- | ------------- | -------------
73+
{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{classname}}_{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{classname}}_{{operationId}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{{summary}}}{{/summary}}
74+
{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
75+
76+
## Documentation for Models
77+
78+
{{#models}}{{#model}} - [{{classname}}_t]({{modelDocPath}}{{classname}}.md)
79+
{{/model}}{{/models}}
80+
81+
## Documentation for Authorization
82+
83+
{{^authMethods}}
84+
All endpoints do not require authorization.
85+
{{/authMethods}}
86+
{{#authMethods}}
87+
{{#last}}
88+
Authentication schemes defined for the API:
89+
{{/last}}
90+
{{/authMethods}}
91+
{{#authMethods}}
92+
93+
### {{name}}
94+
95+
{{#isApiKey}}- **Type**: API key
96+
97+
- **API key parameter name**: {{keyParamName}}
98+
- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
99+
{{/isApiKey}}
100+
{{#isBasic}}
101+
102+
- **Type**: HTTP basic authentication
103+
{{/isBasic}}
104+
{{#isOAuth}}
105+
106+
- **Type**: OAuth
107+
- **Flow**: {{flow}}
108+
- **Authorization URL**: {{authorizationUrl}}
109+
- **Scopes**: {{^scopes}}N/A{{/scopes}}
110+
{{#scopes}} - {{scope}}: {{description}}
111+
{{/scopes}}
112+
{{/isOAuth}}
113+
114+
{{/authMethods}}
115+
67116
## Author
68117

69118
{{#apiInfo}}{{#apis}}{{#-last}}{{infoEmail}}

‎modules/openapi-generator/src/main/resources/C-libcurl/api_doc.mustache

+60
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# {{classname}}{{#description}}
2+
{{description}}{{/description}}
3+
4+
All URIs are relative to *{{basePath}}*
5+
6+
Method | HTTP request | Description
7+
------------- | ------------- | -------------
8+
{{#operations}}{{#operation}}[**{{classname}}_{{operationId}}**]({{classname}}.md#{{classname}}_{{operationId}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
9+
{{/operation}}{{/operations}}
10+
11+
{{#operations}}
12+
{{#operation}}
13+
# **{{classname}}_{{{operationId}}}**
14+
```c
15+
{{#summary}}
16+
// {{{summary}}}
17+
//
18+
{{/summary}}
19+
{{#notes}}
20+
// {{{notes}}}
21+
//
22+
{{/notes}}
23+
{{#returnType}}{{#returnTypeIsPrimitive}}{{#returnSimpleType}}{{{.}}}*{{/returnSimpleType}}{{^returnSimpleType}}{{#isArray}}{{{.}}}_t*{{/isArray}}{{#isMap}}{{{.}}}{{/isMap}}{{/returnSimpleType}}{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}{{{.}}}_t*{{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}void{{/returnType}} {{{classname}}}_{{{operationId}}}(apiClient_t *apiClient{{#allParams}}, {{#isPrimitiveType}}{{#isNumber}}{{{dataType}}}{{/isNumber}}{{#isLong}}{{{dataType}}}{{/isLong}}{{#isInteger}}{{{dataType}}}{{/isInteger}}{{#isDouble}}{{{dataType}}}{{/isDouble}}{{#isFloat}}{{{dataType}}}{{/isFloat}}{{#isBoolean}}{{dataType}}{{/isBoolean}}{{#isEnum}}{{#isString}}{{projectName}}_{{operationId}}_{{baseName}}_e{{/isString}}{{/isEnum}}{{^isEnum}}{{#isString}}{{{dataType}}} *{{/isString}}{{/isEnum}}{{#isByteArray}}{{{dataType}}}{{/isByteArray}}{{#isDate}}{{{dataType}}}{{/isDate}}{{#isDateTime}}{{{dataType}}}{{/isDateTime}}{{#isFile}}{{{dataType}}}{{/isFile}}{{#isFreeFormObject}}{{dataType}}_t *{{/isFreeFormObject}}{{/isPrimitiveType}}{{^isArray}}{{^isPrimitiveType}}{{#isModel}}{{#isEnum}}{{datatypeWithEnum}}_e{{/isEnum}}{{^isEnum}}{{{dataType}}}_t *{{/isEnum}}{{/isModel}}{{^isModel}}{{#isEnum}}{{datatypeWithEnum}}_e{{/isEnum}}{{/isModel}}{{#isUuid}}{{dataType}} *{{/isUuid}}{{#isEmail}}{{dataType}}{{/isEmail}}{{/isPrimitiveType}}{{/isArray}}{{#isContainer}}{{#isArray}}{{dataType}}_t *{{/isArray}}{{#isMap}}{{dataType}}{{/isMap}}{{/isContainer}} {{{paramName}}}{{/allParams}});
24+
```
25+
26+
### Parameters
27+
Name | Type | Description | Notes
28+
------------- | ------------- | ------------- | -------------
29+
**apiClient** | **apiClient_t \*** | context containing the client configuration |
30+
{{#allParams}}
31+
**{{paramName}}** | {{#isPrimitiveType}}{{#isNumber}}**{{{dataType}}}**{{/isNumber}}{{#isLong}}**{{{dataType}}}**{{/isLong}}{{#isInteger}}**{{{dataType}}}**{{/isInteger}}{{#isDouble}}**{{{dataType}}}**{{/isDouble}}{{#isFloat}}**{{{dataType}}}**{{/isFloat}}{{#isBoolean}}**{{dataType}}**{{/isBoolean}}{{#isEnum}}{{#isString}}**{{projectName}}_{{operationId}}_{{baseName}}_e**{{/isString}}{{/isEnum}}{{^isEnum}}{{#isString}}**{{{dataType}}} \***{{/isString}}{{/isEnum}}{{#isByteArray}}**{{{dataType}}}**{{/isByteArray}}{{#isDate}}**{{{dataType}}}**{{/isDate}}{{#isDateTime}}**{{{dataType}}}**{{/isDateTime}}{{#isFile}}**{{{dataType}}}**{{/isFile}}{{#isFreeFormObject}}**[{{dataType}}_t]({{baseType}}.md) \***{{/isFreeFormObject}}{{/isPrimitiveType}}{{^isArray}}{{^isPrimitiveType}}{{#isModel}}{{#isEnum}}**{{datatypeWithEnum}}_e**{{/isEnum}}{{^isEnum}}**[{{{dataType}}}_t]({{{baseType}}}.md) \***{{/isEnum}}{{/isModel}}{{^isModel}}{{#isEnum}}**{{datatypeWithEnum}}_e**{{/isEnum}}{{/isModel}}{{#isUuid}}**{{dataType}} \***{{/isUuid}}{{#isEmail}}**{{dataType}}**{{/isEmail}}{{/isPrimitiveType}}{{/isArray}}{{#isContainer}}{{#isArray}}**[{{dataType}}_t]({{baseType}}.md) \***{{/isArray}}{{#isMap}}**{{dataType}}**{{/isMap}}{{/isContainer}} | {{description}} | {{^required}}[optional] {{/required}}{{#defaultValue}}[default to {{defaultValue}}]{{/defaultValue}}
32+
{{/allParams}}
33+
34+
### Return type
35+
36+
{{#returnType}}
37+
{{#returnTypeIsPrimitive}}
38+
{{#returnSimpleType}}{{{.}}}*{{/returnSimpleType}}
39+
{{^returnSimpleType}}
40+
{{#isArray}}[{{{.}}}_t]({{returnBaseType}}.md) *{{/isArray}}
41+
{{#isMap}}{{{.}}}{{/isMap}}
42+
{{/returnSimpleType}}
43+
{{/returnTypeIsPrimitive}}
44+
{{^returnTypeIsPrimitive}}[{{{.}}}_t]({{returnBaseType}}.md) *{{/returnTypeIsPrimitive}}
45+
{{/returnType}}
46+
{{^returnType}}void{{/returnType}}
47+
48+
### Authorization
49+
50+
{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{{name}}}](../README.md#{{{name}}}){{^-last}}, {{/-last}}{{/authMethods}}
51+
52+
### HTTP request headers
53+
54+
- **Content-Type**: {{#consumes}}{{{mediaType}}}{{^-last}}, {{/-last}}{{/consumes}}{{^consumes}}Not defined{{/consumes}}
55+
- **Accept**: {{#produces}}{{{mediaType}}}{{^-last}}, {{/-last}}{{/produces}}{{^produces}}Not defined{{/produces}}
56+
57+
[[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)
58+
59+
{{/operation}}
60+
{{/operations}}

‎modules/openapi-generator/src/main/resources/C-libcurl/model_doc.mustache

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{{#models}}{{#model}}# {{classname}}_t
2+
3+
## Properties
4+
Name | Type | Description | Notes
5+
------------ | ------------- | ------------- | -------------
6+
{{#vars}}
7+
**{{name}}** | {{^isContainer}}{{^isPrimitiveType}}{{#isModel}}{{#isEnum}}**{{projectName}}_{{classVarName}}_{{enumName}}_e**{{/isEnum}}{{^isEnum}}[**{{datatype}}_t**]({{complexType}}.md) \*{{/isEnum}}{{/isModel}}{{#isUuid}}**{{datatype}} \***{{/isUuid}}{{#isEmail}}**{{datatype}} \***{{/isEmail}}{{#isFreeFormObject}}[**{{datatype}}_t**]({{complexType}}.md) \*{{/isFreeFormObject}}{{/isPrimitiveType}}{{#isPrimitiveType}}{{#isNumeric}}**{{datatype}}**{{/isNumeric}}{{#isBoolean}}**{{datatype}}**{{/isBoolean}}{{#isEnum}}{{#isString}}**{{projectName}}_{{classVarName}}_{{enumName}}_e**{{/isString}}{{/isEnum}}{{^isEnum}}{{#isString}}**{{datatype}} \***{{/isString}}{{/isEnum}}{{#isByteArray}}**{{datatype}}**{{/isByteArray}}{{#isBinary}}**{{datatype}}**{{/isBinary}}{{#isDate}}**{{datatype}} \***{{/isDate}}{{#isDateTime}}**{{datatype}} \***{{/isDateTime}}{{/isPrimitiveType}}{{/isContainer}}{{#isContainer}}{{#isArray}}{{#isPrimitiveType}}**{{datatype}}_t \***{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{datatype}}_t**]({{complexType}}.md) \*{{/isPrimitiveType}}{{/isArray}}{{#isMap}}**{{datatype}}**{{/isMap}}{{/isContainer}} | {{description}} | {{^required}}[optional] {{/required}}{{#isReadOnly}}[readonly] {{/isReadOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}}
8+
{{/vars}}
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+
{{/model}}{{/models}}

‎samples/client/petstore/c/.openapi-generator/FILES

+9
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,15 @@ api/StoreAPI.c
55
api/StoreAPI.h
66
api/UserAPI.c
77
api/UserAPI.h
8+
docs/PetAPI.md
9+
docs/StoreAPI.md
10+
docs/UserAPI.md
11+
docs/api_response.md
12+
docs/category.md
13+
docs/order.md
14+
docs/pet.md
15+
docs/tag.md
16+
docs/user.md
817
external/cJSON.c
918
external/cJSON.h
1019
external/cJSON.licence

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

+60
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,66 @@ Once compiled, you can run it with ``` ./main ```
5858

5959
Note: You don't need to specify includes for models and include folder seperately as they are path linked. You just have to import the api.h file in your code, the include linking will work.
6060

61+
## Documentation for API Endpoints
62+
63+
All URIs are relative to *http://petstore.swagger.io/v2*
64+
65+
Category | Method | HTTP request | Description
66+
------------ | ------------- | ------------- | -------------
67+
*PetAPI* | [**PetAPI_addPet**](docs/PetAPI.md#PetAPI_addPet) | **POST** /pet | Add a new pet to the store
68+
*PetAPI* | [**PetAPI_deletePet**](docs/PetAPI.md#PetAPI_deletePet) | **DELETE** /pet/{petId} | Deletes a pet
69+
*PetAPI* | [**PetAPI_findPetsByStatus**](docs/PetAPI.md#PetAPI_findPetsByStatus) | **GET** /pet/findByStatus | Finds Pets by status
70+
*PetAPI* | [**PetAPI_findPetsByTags**](docs/PetAPI.md#PetAPI_findPetsByTags) | **GET** /pet/findByTags | Finds Pets by tags
71+
*PetAPI* | [**PetAPI_getPetById**](docs/PetAPI.md#PetAPI_getPetById) | **GET** /pet/{petId} | Find pet by ID
72+
*PetAPI* | [**PetAPI_updatePet**](docs/PetAPI.md#PetAPI_updatePet) | **PUT** /pet | Update an existing pet
73+
*PetAPI* | [**PetAPI_updatePetWithForm**](docs/PetAPI.md#PetAPI_updatePetWithForm) | **POST** /pet/{petId} | Updates a pet in the store with form data
74+
*PetAPI* | [**PetAPI_uploadFile**](docs/PetAPI.md#PetAPI_uploadFile) | **POST** /pet/{petId}/uploadImage | uploads an image
75+
*StoreAPI* | [**StoreAPI_deleteOrder**](docs/StoreAPI.md#StoreAPI_deleteOrder) | **DELETE** /store/order/{orderId} | Delete purchase order by ID
76+
*StoreAPI* | [**StoreAPI_getInventory**](docs/StoreAPI.md#StoreAPI_getInventory) | **GET** /store/inventory | Returns pet inventories by status
77+
*StoreAPI* | [**StoreAPI_getOrderById**](docs/StoreAPI.md#StoreAPI_getOrderById) | **GET** /store/order/{orderId} | Find purchase order by ID
78+
*StoreAPI* | [**StoreAPI_placeOrder**](docs/StoreAPI.md#StoreAPI_placeOrder) | **POST** /store/order | Place an order for a pet
79+
*UserAPI* | [**UserAPI_createUser**](docs/UserAPI.md#UserAPI_createUser) | **POST** /user | Create user
80+
*UserAPI* | [**UserAPI_createUsersWithArrayInput**](docs/UserAPI.md#UserAPI_createUsersWithArrayInput) | **POST** /user/createWithArray | Creates list of users with given input array
81+
*UserAPI* | [**UserAPI_createUsersWithListInput**](docs/UserAPI.md#UserAPI_createUsersWithListInput) | **POST** /user/createWithList | Creates list of users with given input array
82+
*UserAPI* | [**UserAPI_deleteUser**](docs/UserAPI.md#UserAPI_deleteUser) | **DELETE** /user/{username} | Delete user
83+
*UserAPI* | [**UserAPI_getUserByName**](docs/UserAPI.md#UserAPI_getUserByName) | **GET** /user/{username} | Get user by user name
84+
*UserAPI* | [**UserAPI_loginUser**](docs/UserAPI.md#UserAPI_loginUser) | **GET** /user/login | Logs user into the system
85+
*UserAPI* | [**UserAPI_logoutUser**](docs/UserAPI.md#UserAPI_logoutUser) | **GET** /user/logout | Logs out current logged in user session
86+
*UserAPI* | [**UserAPI_updateUser**](docs/UserAPI.md#UserAPI_updateUser) | **PUT** /user/{username} | Updated user
87+
88+
89+
## Documentation for Models
90+
91+
- [api_response_t](docs/api_response.md)
92+
- [category_t](docs/category.md)
93+
- [order_t](docs/order.md)
94+
- [pet_t](docs/pet.md)
95+
- [tag_t](docs/tag.md)
96+
- [user_t](docs/user.md)
97+
98+
99+
## Documentation for Authorization
100+
101+
102+
### api_key
103+
104+
- **Type**: API key
105+
106+
- **API key parameter name**: api_key
107+
- **Location**: HTTP header
108+
109+
110+
### petstore_auth
111+
112+
113+
- **Type**: OAuth
114+
- **Flow**: implicit
115+
- **Authorization URL**: http://petstore.swagger.io/api/oauth/dialog
116+
- **Scopes**:
117+
- write:pets: modify pets in your account
118+
- read:pets: read your pets
119+
120+
61121
## Author
62122

63123

0 commit comments

Comments
 (0)