Swagger Code Generation Prepare
Prepare swagger definition for template engine consumption.
This is adapted from swagger-js-codegen, only keeping the logic that prepares the object for template engine. This is intended to be used in conjunction with either mustache or handlebars.
Installation
npm install swagger-codegen-prepare
Template Variables
The following data are passed to the mustache templates:
description: type: string description: Provided by your options field: 'swagger.info.description'isSecure: type: boolean description: false unless 'swagger.securityDefinitions' is definedmoduleName: type: string description: Your AngularJS module name - provided by your options fieldclassName: type: string description: Provided by your options fielddomain: type: string description: If all options defined: swagger.schemes[0] + '://' + swagger.host + swagger.basePathinfo: type: string description: Provided by your options field: 'swagger.info' host: type: string description: Provided by your options field: 'swagger.host' basePath: type: string description: Provided by your options field: 'swagger.basePath' methods: type: array items: type: object properties: path: type: string className: type: string description: Provided by your options field methodName: type: string description: Generated from the HTTP method and path elements or 'x-swagger-js-method-name' field method: type: string description: 'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'COPY', 'HEAD', 'OPTIONS', 'LINK', 'UNLIK', 'PURGE', 'LOCK', 'UNLOCK', 'PROPFIND' enum: - GET - POST - PUT - DELETE - PATCH - COPY - HEAD - OPTIONS - LINK - UNLIK - PURGE - LOCK - UNLOCK - PROPFIND isGET: type: string description: true if method === 'GET' summary: type: string description: Provided by the 'description' or 'summary' field in the schema externalDocs: type: object properties: url: type: string description: The URL for the target documentation. Value MUST be in the format of a URL. required: true description: type: string description: A short description of the target documentation. GitHub-Markdown syntax can be used for rich text representation. isSecure: type: boolean description: true if the 'security' is defined for the method in the schema parameters: type: array description: Includes all of the properties defined for the parameter in the schema plus: items: camelCaseName: type: string isSingleton: type: boolean description: true if there was only one 'enum' defined for the parameter singleton: type: string description: the one and only 'enum' defined for the parameter (if there is only one) isBodyParameter: type: boolean isPathParameter: type: boolean isQueryParameter: type: boolean isPatternType: type: boolean description: true if *in* is 'query', and 'pattern' is defined isHeaderParameter: type: boolean isFormParameter: type: boolean byIn: type: object description: parameters grouped by 'in'. items: path: type: parameter query: type: parameter body: type: parameter header: type: parameter formData: type: parameter hasPath: type: boolean hasQuery: type: boolean hasBody: type: boolean hasHeader: type: boolean hasFormData: type: boolean consumes: type: object produces: type: object hasConsumes: type: boolean description: consumes section exists. hasProduces: type: boolean description: produces section exists.
Simple Example
Prepare swagger, then use a handlebars template to generate output from the definition.
var Handlebars = ;var prep = ;var swagger = ;var data = prep;// Dump a list of methods and descriptionsvar source = '{{className}}' '{{#methods}}' ' - {{methodName}} : {{summary}}' '{{/methods}}';var template = Handlebars;var result = ;console;
Output of the above code for the petstore example.
PetStore
- addPet : Add a new pet to the store
- updatePet : Update an existing pet
- findPetsByStatus : Multiple status values can be provided with comma separated strings
- findPetsByTags : Muliple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.
- getPetById : Returns a single pet
- updatePetWithForm : Updates a pet in the store with form data
- deletePet : Deletes a pet
- uploadFile : uploads an image
- getInventory : Returns a map of status codes to quantities
- placeOrder : Place an order for a pet
- getOrderById : For valid response try integer IDs with value >= 1 and <= 10. Other values will generated exceptions
- deleteOrder : For valid response try integer IDs with positive integer value. Negative or non-integer values will generate API errors
- createUser : This can only be done by the logged in user.
- createUsersWithArrayInput : Creates list of users with given input array
- createUsersWithListInput : Creates list of users with given input array
- loginUser : Logs user into the system
- logoutUser : Logs out current logged in user session
- getUserByName : Get user by user name
- updateUser : This can only be done by the logged in user.
- deleteUser : This can only be done by the logged in user.
Example Code Generator
Example using the optional 'convertType' method and 'defaultType' parameter.
var Handlebars = ;var prep = ;var swagger = ;var { var name = "std::string"; var isRef = false; if swaggerTypeschema if swaggerTypeschematype || swaggerTypeschema$ref return ; if swaggerTypetype === 'array' isRef = true; if swaggerTypeitems name = "std::vector< " + name + " >"; else name = "std::vector< std::string >"; else if swaggerTypetype === 'integer' name = "int"; else if swaggerTypetype && swaggerTypetype !== "string" && swaggerTypetype !== "file" name = swaggerTypetype; if swaggerType$ref name = swaggerType$ref; isRef = true; return name: name isRef: isRef ;};var data = prep;var source = 'class {{className}}_iface {' 'public:' ' {{#methods}}' ' //-------------------------' ' //{{&summary}}' ' virtual {{&return.__type.name}} {{&methodName}}(' '{{#parameters}}' '{{#notFirstParameter}} , {{/notFirstParameter}}' '{{&__type.name}} {{#__type.isRef}}&{{/__type.isRef}}{{&name}}' '{{/parameters}}' ') = NULL;' '{{/methods}}' '};' '{{#definitions}}' '{{#hasProperties}}' '' 'class {{name}} {' 'public:' '{{#properties}}' ' {{&__type.name}} {{&name}};' '{{/properties}}' '};' '{{/hasProperties}}' '{{/definitions}}';var template = Handlebars;var result = ;console;
Running the above example with the Petstore swagger example produces the below content.
; ; ; ; ; ; ;
Example Producing HTML Documentation
The following script produces a rough approximation of the document output from swaggers html generator.
var Handlebars = ;var prep = ;var swagger = ;var data = prep;var fs = ;var source = fs;var template = Handlebars;var result = ;console;
The 'htmldoc.mustache' template file used by the above script.
{{info.title}} {{#info}}{{title}}{{description}}{{#contact}}Contact Info: {{email}}{{/contact}}{{version}}{{#license}}{{name}}{{url}}{{/license}}{{/info}} BasePath:{{basePath}}MethodsTable of Contents {{#byTags}}{{#tags}}{{name}}{{description}}{{/tags}}{{#methods}}{{method}} {{path}}{{/methods}}{{/byTags}}{{className}}{{#methods}}Up{{method}} {{path}}{{summary}}{{#hasConsumes}} Consumes This API call consumes the following media types via the Content-Type request header: {{#consumes}} {{.}} {{/consumes}} {{/hasConsumes}}{{#byIn}}{{#hasPath}}Path parameters {{#path}} {{name}} {{#required}}(required){{/required}} Path Parameter — {{description}} {{/path}}{{/hasPath}}{{#hasQuery}}Query parameters {{#query}} {{name}} {{#required}}(required){{/required}} Query Parameter — {{description}} {{/query}}{{/hasQuery}}{{#hasBody}}Request body {{#body}} {{name}} {{#required}}(required){{/required}} Body Parameter — {{description}} {{/body}}{{/hasBody}} {{#hasHeader}}Header parameters {{#header}} {{name}} {{#required}}(required){{/required}} Header Parameter — {{description}} {{/header}}{{/hasHeader}} {{#hasFormData}}Form parameters {{#formData}} {{name}} {{#required}}(required){{/required}} Form Parameter — {{description}} {{/formData}}{{/hasFormData}} {{/byIn}}{{#hasProduces}} Produces This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header. {{#produces}} {{.}} {{/produces}} {{/hasProduces}}{{#hasResponses}} Responses{{#responses}} {{responseCode}} {{description}}{{/responses}}{{/hasResponses}}{{/methods}}ModelsTable of Contents{{#definitions}} {{name}} - {{/definitions}} {{#definitions}} {{name}} - Up {{#properties}}{{name}} {{definition.type}} format: {{definition.format}} {{/properties}} <!-- field-items --> {{/definitions}}