🛠️ Apigen

Welcome to apigen.springboot, made in spain , the opensource project in Java that allows you to generate an archetype of the springboot framework using the openapi file as a mapping tool between the openapi definition and the database. Click maven to see available mvnrepository dependencies.

This repository is intended for community use, it can be modified and adapted without commercial use. If you need a version, support or help for your enterprise or project, please contact us 📧 devrel@apiaddicts.org

🙌 Join the Apigen Adopters list

📢 If Apigen is part of your organization's toolkit, we kindly encourage you to include your company's name in our Adopters list. 🙏 This not only significantly boosts the project's visibility and reputation but also represents a small yet impactful way to give back to the project.

Organization	Description of Use / Referenc
CloudAppi	Apification and generation of microservices
Acciona	Generation of microservices
Madrid Digital	Generation of microservices
Apiquality	Generation of microservices

👩🏽‍💻 Contribute to ApiAddicts

We're an inclusive and open community, welcoming you to join our effort to enhance ApiAddicts, and we're excited to prioritize tasks based on community input, inviting you to review and collaborate through our GitHub issue tracker.

Feel free to drop by and greet us on our GitHub discussion or Discord chat. You can also show your support by giving us some GitHub stars ⭐️, or by following us on Twitter, LinkedIn, and subscribing to our YouTube channel! 🚀

📑 Getting started

🖥️ CLI

java -jar generator-cli.jar generate -f openapi.yaml -o ./code
java -jar generator-cli.jar help

🐋 Docker compose

version: "3.3"services:
apigen:
image: "apiaddicts/apitools-apigen:2.1.1"ports:
- "8080:8080"

curl -X POST "http://localhost:8080/generator/file" \
-F "file=@openapi.yaml"

Project

Scheme

x-apigen-project:
name: string
description: string
version: string
java-properties:
group-id: string
artifact-id: string

Definition

• x-apigen-project: Section where project information is defined
  • name: Project name
  • description: Brief project description
  • version: Project version
  • java-properties: Section where specific Java project information is defined
    • group-id: Initial package name where the project resides. If it consists of multiple words, they will be separated by .
    • artifact-id: Identifier name for the project
    • base-package: Name of the base package to use in the generated code; if not specified, it is obtained from the group-id and artifact-id
  • standard-response-operations: Section where standard apigen response transformation operations are defined (optional)
    • <jsonpatch operation node>: Node that complies with the json-patch standard, allowing optional operations to be declared on all elements of an array

Samples

x-apigen-project:
name: Colors
description: This would be the Colors project
version: 1.0.0
java-properties:
group-id: the.group
artifact-id: app

Models

Scheme

x-apigen-models:
<model_name>:
relational-persistence:
table: string
attributes:
- name: string
type: string [ENUM[Array, String, Boolean, Double, Float, BigDecimal, Integer, Long, BigInteger, LocalDate, LocalDateTime, ZonedDateTime, OffsetDateTime, Instant, ComposedID] o <model_name>]
items-type: string [<model_name>]
relational-persistence:
column: string
primary-key: boolean
foreign-column: string
intermediate-table: string
owner: boolean
validations:
- type: string [ENUM[NotNull, Size, Min, Max, Email, NotEmpty, NotBlank, Positive, PositiveOrZero, Negative, NegativeOrZero, Past, PastOrPresent, Future, FutureOrPresent, Pattern, Digits, DecimalMin, DecimalMax]]
min: integer
max: integer
regex: string
value: integer | string
integer: integer
fraction: integer
inclusive: boolean 

Definition

• x-apigen-models: Section where project models are defined
  • <model_name>: Name of the model
    • relational-persistence: Section where all aspects related to the model's relational persistence are indicated
      • table: Name of the table in the database
    • attributes: Section that contains the model's attributes
      • name: Name of the attribute
      • type: Type of the attribute, supported types are: [Array, String, Boolean, Double, Float, Integer, Long, LocalDate, OffsetDateTime, ComposedID], or in the case of another model, the name of that model
      • items-type: In the case of the type being an Array, this field should be defined with the name of the referenced model
      • attributes: Similar to the attributes of the model, only used when the type is ComposedID to indicate the attributes that make up the identifier
      • relational-persistence: Section where all aspects related to the relational persistence of the model's attribute are indicated
        • column: Name of the column in the database
        • columns: Relationship of columns from the current table to another related table when dealing with a model with a composite identifier (each entry is defined as key: value where the key is the name in the current table and the value is the name in the related table)
        • primary-key: Indicates if it is the primary key, if not specified, the default value will be false
        • foreign-column: Indicates the name of the column in the related table
        • foreign-columns: Relationship of columns in the related table to the current table when dealing with a model with a composite identifier (each entry is defined as key: value where the key is the name in the related table and the value is the name in the current table)
        • intermediate-table: Name of the intermediate table in those attributes that represent a many-to-many relationship
        • owner: Indicates if this part of the relationship is the owner, necessary in one-to-one or one-to-many relationships
        • sequence: Section where the optional generator to use for the primary key can be indicated
      • validations: Section where attribute validations are defined
        • type: The supported types for validation are as follows: [NotNull, Size, Min, Max, Email, NotEmpty, NotBlank, Positive, PositiveOrZero, Negative, NegativeOrZero, Past, PastOrPresent, Future, FutureOrPresent, Pattern, Digits, DecimalMin, DecimalMax]
        • min: Value used when the type field is Size
        • max: Value used when the type field is Size
        • regex: Value used when the type field is Pattern
        • value: Value used when the type field is Min, Max, DecimalMin, or DecimalMax
        • integer: Value used when the type field is Digits, representing the maximum number of digits in the integer part of the number
        • fraction: Value used when the type field is Digits, representing the maximum number of digits in the decimal part of the number
        • inclusive: Value used when the type field is DecimalMin or DecimalMax

Samples

x-apigen-models:
Color:
relational-persistence:
table: colors
attributes:
- name: id
type: Long
relational-persistence:
column: id
primary-key: true
validations:
- type: NotNull
- name: name
type: String
relational-persistence:
column: name
validations:
- type: Pattern
regex: [A-Z]+
Composed:
relational-persistence:
table: composed
attributres:
- name: id
type: ComposedID
validations:
- type: NotNull
attributes:
- name: one
type: String
relational-persistence:
column: c_one
validations:
- type: NotNull
- name: two
type: Integer relational-persistence:
column: c_two validations:
- type: NotNull

Path expansion

Scheme

paths:
<path>:
...
x-apigen-binding:
model: string

Definition

• x-apigen-binding: Section where the connection between the endpoint and the model we will use is defined
  • model: In this field, we can specify the name of the model.
  • child-model: In this field, we will put the name of the child model. Only necessary for self-managed endpoints of parent-child type entities.
  • child-parent-relation-property: In this field, we will put the name of the property in the child that relates to the parent. Only necessary for self-managed endpoints of parent-child type entities.

Sample

paths:
/colors:
x-apigen-binding:
model: Color

Extension of the schema section of the requestBody

Scheme

schemas:
<schema>:
x-apigen-mapping:
model: string
type: object
properties:
<prop_name>:
type: string
x-apigen-mapping:
model: string
field: string
<prop_name_2>:
x-apigen-mapping:
model: string

Definition

• x-apigen-mapping: Section where all mapping data between resources and models are defined. Each attribute of an input resource, including the input resource itself, can have this section defined. If it is not defined, it is assumed to have the default values indicated in each section.
  • model: Name of the model that the resource or attribute represents. If not specified at the resource level, it is not considered a standard input resource.
  • field: Name of the model attribute to which the resource attribute will be mapped. By default, if nothing is specified, it will be mapped to an attribute with the same name if it exists; otherwise, it will be ignored. There are two specific cases in which it is mandatory to define this field:
    • When the name of the attribute in the resource and in the model are different:

      nombre:
      type: stringx-apigen-mapping:
      field: primerNombre

    • When the attribute in the resource is an abbreviation of the identifier of a nested model:

      color:
      type: stringx-apigen-mapping:
      model: colorfield: valorCromatico.id

Expansion of the response outline section

Preconditions

The Apigen extension for OpenAPI forces us to take into account a series of conditions so that endpoint responses comply with the standard.

Have a defined standard response

schemas:
standard_response_result:
properties:
result:
type: objectproperties:
status:
type: booleanhttp_code:
type: integererrors:
type: arrayitems:
$ref: '#/components/schemas/standard_error'info:
type: stringtrace_id:
type: stringnum_elements:
type: integerrequired:
- status
- http_code
- trace_idstandard_error:
type: objectproperties:
code:
type: integermessage:
type: string

Have a single standard collection response defined for each model

schemas:
standard_response_collection_<model>:
allOf:
- $ref: "#/components/schemas/standard_response_result"
- type: objectproperties:
data:
type: objectproperties:
<model_plural>:
type: arrayitems:
$ref: "#/components/schemas/<model_resource>"

Have a single simple standard response defined for each model

schemas:
standard_response_<model>:
allOf:
- $ref: "#/components/schemas/standard_response_result"
- type: objectproperties:
data:
$ref: "#/components/schemas/<model_resource>"

Scheme

schemas:
<schema>:
x-apigen-mapping:
model: string
type: object
properties:
<prop_name>:
type: string
x-apigen-mapping:
field: string

Definition

• x-apigen-mapping: Section where all mapping data between resources and models are defined. Each output resource must have this section defined.
  • model: Name of the model that the resource represents.
  • field: Name of the model attribute to which the resource attribute will be mapped.

Sample

color:
x-apigen-mapping:
model: Color
type: object
properties:
json_id:
type: integer
x-apigen-mapping:
field: id
name:
type: string
forms:
$ref: "#/components/schemas/forms"

💛 Sponsors