Skip to content

Commit a019e13

Browse files
wing328wing328
committed
Merge pull request #2388 from wing328/php_api_doc
[PHP] Add documentation (markdown) to APIs and models
2 parents 1e73193 + 2eda3b1 commit a019e13

33 files changed

+1774
-80
lines changed

‎modules/swagger-codegen/src/main/java/io/swagger/codegen/CodegenOperation.java

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ public class CodegenOperation {
3232
public ExternalDocs externalDocs;
3333
public Map<String, Object> vendorExtensions;
3434
public String nickname; // legacy support
35+
public String operationIdLowerCase; // for mardown documentation
3536

3637
/**
3738
* Check if there's at least one parameter

‎modules/swagger-codegen/src/main/java/io/swagger/codegen/DefaultCodegen.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1575,7 +1575,6 @@ public int compare(CodegenParameter one, CodegenParameter another) {
15751575
// legacy support
15761576
op.nickname = op.operationId;
15771577

1578-
15791578
if (op.allParams.size() > 0) {
15801579
op.hasParams = true;
15811580
}
@@ -2075,6 +2074,7 @@ public void addOperationToGroup(String tag, String resourcePath, Operation opera
20752074
LOGGER.warn("generated unique operationId `" + uniqueName + "`");
20762075
}
20772076
co.operationId = uniqueName;
2077+
co.operationIdLowerCase = uniqueName.toLowerCase();
20782078
opList.add(co);
20792079
co.baseName = tag;
20802080
}

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

Lines changed: 99 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
import io.swagger.codegen.CliOption;
44
import io.swagger.codegen.CodegenConfig;
55
import io.swagger.codegen.CodegenConstants;
6+
import io.swagger.codegen.CodegenParameter;
67
import io.swagger.codegen.CodegenType;
78
import io.swagger.codegen.DefaultCodegen;
89
import io.swagger.codegen.SupportingFile;
@@ -35,6 +36,8 @@ public class PhpClientCodegen extends DefaultCodegen implements CodegenConfig {
3536
protected String artifactVersion = "1.0.0";
3637
protected String srcBasePath = "lib";
3738
protected String variableNamingConvention= "snake_case";
39+
protected String apiDocPath = "docs/";
40+
protected String modelDocPath = "docs/";
3841

3942
public PhpClientCodegen() {
4043
super();
@@ -49,6 +52,9 @@ public PhpClientCodegen() {
4952
modelPackage = invokerPackage + "\\Model";
5053
testPackage = invokerPackage + "\\Tests";
5154

55+
modelDocTemplateFiles.put("model_doc.mustache", ".md");
56+
apiDocTemplateFiles.put("api_doc.mustache", ".md");
57+
5258
setReservedWordsLowerCase(
5359
Arrays.asList(
5460
// local variables used in api methods (endpoints)
@@ -110,8 +116,8 @@ public PhpClientCodegen() {
110116
cliOptions.add(new CliOption(CodegenConstants.INVOKER_PACKAGE, "The main namespace to use for all classes. e.g. Yay\\Pets"));
111117
cliOptions.add(new CliOption(PACKAGE_PATH, "The main package name for classes. e.g. GeneratedPetstore"));
112118
cliOptions.add(new CliOption(SRC_BASE_PATH, "The directory under packagePath to serve as source root."));
113-
cliOptions.add(new CliOption(COMPOSER_VENDOR_NAME, "The vendor name used in the composer package name. The template uses {{composerVendorName}}/{{composerProjectName}} for the composer package name. e.g. yaypets"));
114-
cliOptions.add(new CliOption(COMPOSER_PROJECT_NAME, "The project name used in the composer package name. The template uses {{composerVendorName}}/{{composerProjectName}} for the composer package name. e.g. petstore-client"));
119+
cliOptions.add(new CliOption(COMPOSER_VENDOR_NAME, "The vendor name used in the composer package name. The template uses {{composerVendorName}}/{{composerProjectName}} for the composer package name. e.g. yaypets. IMPORTANT NOTE (2016/03): composerVendorName will be deprecated and replaced by gitUserId in the next swagger-codegen release"));
120+
cliOptions.add(new CliOption(COMPOSER_PROJECT_NAME, "The project name used in the composer package name. The template uses {{composerVendorName}}/{{composerProjectName}} for the composer package name. e.g. petstore-client. IMPORTANT NOTE (2016/03): composerProjectName will be deprecated and replaced by gitRepoId in the next swagger-codegen release"));
115121
cliOptions.add(new CliOption(CodegenConstants.ARTIFACT_VERSION, "The version to use in the composer package version field. e.g. 1.2.3"));
116122
}
117123

@@ -217,6 +223,10 @@ public void processOpts() {
217223

218224
additionalProperties.put("escapedInvokerPackage", invokerPackage.replace("\\", "\\\\"));
219225

226+
// make api and model doc path available in mustache template
227+
additionalProperties.put("apiDocPath", apiDocPath);
228+
additionalProperties.put("modelDocPath", modelDocPath);
229+
220230
supportingFiles.add(new SupportingFile("configuration.mustache", toPackagePath(invokerPackage, srcBasePath), "Configuration.php"));
221231
supportingFiles.add(new SupportingFile("ApiClient.mustache", toPackagePath(invokerPackage, srcBasePath), "ApiClient.php"));
222232
supportingFiles.add(new SupportingFile("ApiException.mustache", toPackagePath(invokerPackage, srcBasePath), "ApiException.php"));
@@ -254,6 +264,28 @@ public String modelTestFileFolder() {
254264
return (outputFolder + "/" + toPackagePath(testPackage, srcBasePath));
255265
}
256266

267+
@Override
268+
public String apiDocFileFolder() {
269+
//return (outputFolder + "/" + apiDocPath).replace('/', File.separatorChar);
270+
return (outputFolder + "/" + getPackagePath() + "/" + apiDocPath);
271+
}
272+
273+
@Override
274+
public String modelDocFileFolder() {
275+
//return (outputFolder + "/" + modelDocPath).replace('/', File.separatorChar);
276+
return (outputFolder + "/" + getPackagePath() + "/" + modelDocPath);
277+
}
278+
279+
@Override
280+
public String toModelDocFilename(String name) {
281+
return toModelName(name);
282+
}
283+
284+
@Override
285+
public String toApiDocFilename(String name) {
286+
return toApiName(name);
287+
}
288+
257289
@Override
258290
public String getTypeDeclaration(Property p) {
259291
if (p instanceof ArrayProperty) {
@@ -460,4 +492,69 @@ public String toDefaultValue(Property p) {
460492
return null;
461493
}
462494

495+
@Override
496+
public void setParameterExampleValue(CodegenParameter p) {
497+
String example;
498+
499+
if (p.defaultValue == null) {
500+
example = p.example;
501+
} else {
502+
example = p.defaultValue;
503+
}
504+
505+
String type = p.baseType;
506+
if (type == null) {
507+
type = p.dataType;
508+
}
509+
510+
if ("String".equalsIgnoreCase(type)) {
511+
if (example == null) {
512+
example = p.paramName + "_example";
513+
}
514+
example = "\"" + escapeText(example) + "\"";
515+
} else if ("Integer".equals(type) || "int".equals(type)) {
516+
if (example == null) {
517+
example = "56";
518+
}
519+
} else if ("Float".equalsIgnoreCase(type) || "Double".equalsIgnoreCase(type)) {
520+
if (example == null) {
521+
example = "3.4";
522+
}
523+
} else if ("BOOLEAN".equalsIgnoreCase(type) || "bool".equalsIgnoreCase(type)) {
524+
if (example == null) {
525+
example = "True";
526+
}
527+
} else if ("\\SplFileObject".equalsIgnoreCase(type)) {
528+
if (example == null) {
529+
example = "/path/to/file";
530+
}
531+
example = "\"" + escapeText(example) + "\"";
532+
} else if ("Date".equalsIgnoreCase(type)) {
533+
if (example == null) {
534+
example = "2013-10-20";
535+
}
536+
example = "new \\DateTime(\"" + escapeText(example) + "\")";
537+
} else if ("DateTime".equalsIgnoreCase(type)) {
538+
if (example == null) {
539+
example = "2013-10-20T19:20:30+01:00";
540+
}
541+
example = "new \\DateTime(\"" + escapeText(example) + "\")";
542+
} else if (!languageSpecificPrimitives.contains(type)) {
543+
// type is a model class, e.g. User
544+
example = "new " + type + "()";
545+
} else {
546+
LOGGER.warn("Type " + type + " not handled properly in setParameterExampleValue");
547+
}
548+
549+
if (example == null) {
550+
example = "NULL";
551+
} else if (Boolean.TRUE.equals(p.isListContainer)) {
552+
example = "array(" + example + ")";
553+
} else if (Boolean.TRUE.equals(p.isMapContainer)) {
554+
example = "array('key' => " + example + ")";
555+
}
556+
557+
p.example = example;
558+
}
559+
463560
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -260,7 +260,7 @@ Class | Method | HTTP request | Description
260260
- **Flow**: {{{flow}}}
261261
- **Authorizatoin URL**: {{{authorizationUrl}}}
262262
- **Scopes**: {{^scopes}}N/A{{/scopes}}
263-
{{#scopes}} - **{{{scope}}}**: {{{description}}}
263+
{{#scopes}} - **{{{scope}}}**: {{{description}}}
264264
{{/scopes}}
265265
{{/isOAuth}}
266266

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

Lines changed: 38 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,11 @@ You can install the bindings via [Composer](http://getcomposer.org/). Add this t
1414
"repositories": [
1515
{
1616
"type": "git",
17-
"url": "https://github.com/{{composerVendorName}}/{{composerProjectName}}.git"
17+
"url": "https://github.com/{{#gitUserId}}{{.}}{{/gitUserId}}{{^gitUserId}}{{composerVendorName}}{{/gitUserId}}/{{#gitRepoId}}{{.}}{{/gitRepoId}}{{^gitRepoId}}{{composerProjectName}}{{/gitRepoId}}.git"
1818
}
1919
],
2020
"require": {
21-
"{{composerVendorName}}/{{composerProjectName}}": "*@dev"
21+
"{{#gitUserId}}{{.}}{{/gitUserId}}{{^gitUserId}}{{composerVendorName}}{{/gitUserId}}/{{#gitRepoId}}{{.}}{{/gitRepoId}}{{^gitRepoId}}{{composerProjectName}}{{/gitRepoId}}": "*@dev"
2222
}
2323
}
2424
```
@@ -40,6 +40,42 @@ composer install
4040
./vendor/bin/phpunit lib/Tests
4141
```
4242

43+
## Documentation for API Endpoints
44+
45+
All URIs are relative to *{{basePath}}*
46+
47+
Class | Method | HTTP request | Description
48+
------------ | ------------- | ------------- | -------------
49+
{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
50+
{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
51+
52+
## Documentation For Models
53+
54+
{{#models}}{{#model}} - [{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
55+
{{/model}}{{/models}}
56+
57+
## Documentation For Authorization
58+
59+
{{^authMethods}} All endpoints do not require authorization.
60+
{{/authMethods}}{{#authMethods}}{{#last}} Authentication schemes defined for the API:{{/last}}{{/authMethods}}
61+
{{#authMethods}}## {{{name}}}
62+
63+
{{#isApiKey}}- **Type**: API key
64+
- **API key parameter name**: {{{keyParamName}}}
65+
- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
66+
{{/isApiKey}}
67+
{{#isBasic}}- **Type**: HTTP basic authentication
68+
{{/isBasic}}
69+
{{#isOAuth}}- **Type**: OAuth
70+
- **Flow**: {{{flow}}}
71+
- **Authorizatoin URL**: {{{authorizationUrl}}}
72+
- **Scopes**: {{^scopes}}N/A{{/scopes}}
73+
{{#scopes}} - **{{{scope}}}**: {{{description}}}
74+
{{/scopes}}
75+
{{/isOAuth}}
76+
77+
{{/authMethods}}
78+
4379
## Author
4480

4581
{{#apiInfo}}{{#apis}}{{^hasMore}}{{infoEmail}}

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

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
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+
### Example
21+
```php
22+
<?php
23+
require_once(__DIR__ . '/vendor/autoload.php');
24+
{{#hasAuthMethods}}{{#authMethods}}{{#isBasic}}
25+
// Configure HTTP basic authorization: {{{name}}}
26+
{{{invokerPackage}}}::getDefaultConfiguration->setUsername('YOUR_USERNAME');
27+
{{{invokerPackage}}}::getDefaultConfiguration->setPassword('YOUR_PASSWORD');{{/isBasic}}{{#isApiKey}}
28+
// Configure API key authorization: {{{name}}}
29+
{{{invokerPackage}}}::getDefaultConfiguration->setApiKey('{{{keyParamName}}}', 'YOUR_API_KEY');
30+
// Uncomment below to setup prefix (e.g. BEARER) for API key, if needed
31+
// {{{invokerPackage}}}::getDefaultConfiguration->setApiKeyPrefix('{{{keyParamName}}}', 'BEARER');{{/isApiKey}}{{#isOAuth}}
32+
// Configure OAuth2 access token for authorization: {{{name}}}
33+
{{{invokerPackage}}}::getDefaultConfiguration->setAccessToken('YOUR_ACCESS_TOKEN');{{/isOAuth}}{{/authMethods}}
34+
{{/hasAuthMethods}}
35+
36+
$api_instance = new {{invokerPackage}}\{{classname}}();
37+
{{#allParams}}${{paramName}} = {{{example}}}; // {{{dataType}}} | {{{description}}}
38+
{{/allParams}}
39+
40+
try {
41+
{{#returnType}}$result = {{/returnType}}$api_instance->{{{operationId}}}({{#allParams}}${{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}});{{#returnType}}
42+
print_r($result);{{/returnType}}
43+
} catch (Exception $e) {
44+
echo 'Exception when calling {{classname}}->{{operationId}}: ', $e->getMessage(), "\n";
45+
}
46+
?>
47+
```
48+
49+
### Parameters
50+
{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}}
51+
Name | Type | Description | Notes
52+
------------- | ------------- | ------------- | -------------{{/-last}}{{/allParams}}
53+
{{#allParams}} **{{paramName}}** | {{#isFile}}**{{dataType}}**{{/isFile}}{{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{^isFile}}[**{{dataType}}**]({{baseType}}.md){{/isFile}}{{/isPrimitiveType}}| {{description}} | {{^required}}[optional] {{/required}}{{#defaultValue}}[default to {{defaultValue}}]{{/defaultValue}}
54+
{{/allParams}}
55+
56+
### Return type
57+
58+
{{#returnType}}{{#returnTypeIsPrimitive}}**{{{returnType}}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}[**{{{returnType}}}**]({{returnBaseType}}.md){{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}void (empty response body){{/returnType}}
59+
60+
### Authorization
61+
62+
{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{{name}}}](../README.md#{{{name}}}){{^-last}}, {{/-last}}{{/authMethods}}
63+
64+
### HTTP reuqest headers
65+
66+
- **Content-Type**: {{#consumes}}{{mediaType}}{{#hasMore}}, {{/hasMore}}{{/consumes}}{{^consumes}}Not defined{{/consumes}}
67+
- **Accept**: {{#produces}}{{mediaType}}{{#hasMore}}, {{/hasMore}}{{/produces}}{{^produces}}Not defined{{/produces}}
68+
69+
[[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)
70+
71+
{{/operation}}
72+
{{/operations}}

‎modules/swagger-codegen/src/main/resources/php/composer.mustache

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"name": "{{composerVendorName}}/{{composerProjectName}}",{{#artifactVersion}}
2+
"name": "{{#gitUserId}}{{.}}{{/gitUserId}}{{^gitUserId}}{{composerVendorName}}{{/gitUserId}}/{{#gitRepoId}}{{.}}{{/gitRepoId}}{{^gitRepoId}}{{composerProjectName}}{{/gitRepoId}}",{{#artifactVersion}}
33
"version": "{{artifactVersion}}",{{/artifactVersion}}
44
"description": "{{description}}",
55
"keywords": [

‎modules/swagger-codegen/src/main/resources/php/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}}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ Class | Method | HTTP request | Description
100100
- **Flow**: {{flow}}
101101
- **Authorizatoin URL**: {{authorizationUrl}}
102102
- **Scopes**: {{^scopes}}N/A{{/scopes}}
103-
{{#scopes}}-- {{scope}}: {{description}}
103+
{{#scopes}} - {{scope}}: {{description}}
104104
{{/scopes}}
105105
{{/isOAuth}}
106106

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ WWW::SwaggerClient::Role - a Moose role for the Swagger Petstore
88

99
Automatically generated by the Perl Swagger Codegen project:
1010

11-
- Build date: 2016-03-13T22:43:11.863+08:00
11+
- Build date: 2016-03-16T15:35:49.140+08:00
1212
- Build package: class io.swagger.codegen.languages.PerlClientCodegen
1313
- Codegen version:
1414

@@ -329,8 +329,8 @@ Class | Method | HTTP request | Description
329329
- **Flow**: implicit
330330
- **Authorizatoin URL**: http://petstore.swagger.io/api/oauth/dialog
331331
- **Scopes**:
332-
- **write:pets**: modify pets in your account
333-
- **read:pets**: read your pets
332+
- **write:pets**: modify pets in your account
333+
- **read:pets**: read your pets
334334

335335

336336

‎samples/client/petstore/perl/lib/WWW/SwaggerClient/Role.pm

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ has version_info => ( is => 'ro',
3737
default => sub { {
3838
app_name => 'Swagger Petstore',
3939
app_version => '1.0.0',
40-
generated_date => '2016-03-13T22:43:11.863+08:00',
40+
generated_date => '2016-03-16T15:35:49.140+08:00',
4141
generator_class => 'class io.swagger.codegen.languages.PerlClientCodegen',
4242
} },
4343
documentation => 'Information about the application version and the codegen codebase version'
@@ -103,7 +103,7 @@ Automatically generated by the Perl Swagger Codegen project:
103103
104104
=over 4
105105
106-
=item Build date: 2016-03-13T22:43:11.863+08:00
106+
=item Build date: 2016-03-16T15:35:49.140+08:00
107107
108108
=item Build package: class io.swagger.codegen.languages.PerlClientCodegen
109109

0 commit comments

Comments
 (0)