Swagger Codegen与Openapi Generator分别的使用过程以及导出SDK

雨点打透心脏的1/2处 2021-09-13 17:18 884阅读 0赞

## Swagger Codegen与Openapi Generator生成SDK的分别的使用过程 ##

### 文章目录 ###

*   *  Swagger Codegen与Openapi Generator生成SDK的分别的使用过程
 *  Swagger Codegen
 *   *  一、Swagger Codegen的安装
     *  二、 Swagger Codegen的使用
 *  Openapi Generator
 *   *  一、Openapi Generator的安装
     *  petstore.yaml文件

# Swagger Codegen #

参考链接：  
[https://github.com/swagger-api/swagger-codegen][https_github.com_swagger-api_swagger-codegen]  
[https://www.jianshu.com/p/14a35d6f7b1a][https_www.jianshu.com_p_14a35d6f7b1a]  
[https://www.cnblogs.com/shamo89/p/7680771.html][https_www.cnblogs.com_shamo89_p_7680771.html]  
可以有很多个版本以及系统（mac，window，linux）可以选择  
https://github.com/swagger-api/swagger-codegen  
中有，根据情况而定：  
这里主要说的linux下的使用和安装：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3N1bnJqX25pdQ_size_16_color_FFFFFF_t_70_pic_center]

## 一、Swagger Codegen的安装 ##

**1.直接命令下载：**

wget https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.15/swagger-codegen-cli-2.4.15.jar -O swagger-codegen-cli.jar

**2.下载好了，运行**

java -jar swagger-codegen-cli.jar

**3.下载之后查看帮助：**

java -jar swagger-codegen-cli.jar help

> 根据返回结果可以看到Swagger Codegen支持的语言有很多:  
> \[android, aspnet5, async-scala,  
> cwiki, csharp, cpprest, dart, flash, python-flask, go, groovy, java,  
> jaxrs, jaxrs-cxf, jaxrs-resteasy, jaxrs-spec, inflector, javascript,  
> javascript-closure-angular, jmeter, nancyfx, nodejs-server, objc,  
> perl, php, python, qt5cpp, ruby, scala, scalatra, silex-PHP, sinatra,  
> rails5, slim, spring, dynamic-html, html, html2, swagger,  
> swagger-yaml, swift, tizen, typescript-angular2, typescript-angular,  
> typescript-node, typescript-fetch, akka-scala, CsharpDotNet2, clojure,  
> haskell, lumen, go-server\]

## 二、 Swagger Codegen的使用 ##

**查看Swagger Codegen支持的具体某个语言的使用帮助，拿java举例**  
「注意在 swagger-codegen-cli.jar的安装路径下执行，否则找不到」：

java -jar swagger-codegen-cli.jar config-help -l java

就会出来很多java语言相关的使用文档：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3N1bnJqX25pdQ_size_16_color_FFFFFF_t_70_pic_center 1]

**利用Swagger Codegen根据服务生成客户端代码**  
必须要在导入该jar的目录下执行  
检测是否可以正常导入：  
我这里是把swagger导出的json数据导出来

java -jar swagger-codegen-cli.jar generate -i http://[你的IP地址或者数据存放地址]:8080/v2/api-docs -l java -o  /usr/local/swagger

\-i http://10.2.0.126:8080/v2/api-docs 代表你要导入的数据  
\-o /usr/local/swagger 代表导出的地址

> 在上面这段代码里，使用了三个参数，分别是-i和-l和-o。
> 
> \-i指定swagger描述文件的路径,url地址或路径文件;该参数为必须(http://petstore.swagger.io/v2/swagger.json是官方的一个例子，我们可以改成自己的服务)
> 
> \-l指定生成客户端代码的语言,该参数为必须
> 
> \-o指定生成文件的位置(默认当前目录)
> 
> 除了可以指定上面三个参数，还有一些常用的：
> 
> \-c json格式的配置文件的路径;文件为json格式,支持的配置项因语言的不同而不同
> 
> \-a 当获取远程swagger定义时,添加授权头信息;URL-encoded格式化的name,逗号隔开的多个值
> 
> –api-package 指定生成的api类的包名
> 
> –artifact-id 指定pom.xml的artifactId的值
> 
> –artifact-version 指定pom.xml的artifact的版本
> 
> –group-id 指定pom.xml的groupId的值
> 
> –model-package 指定生成的model类的包名
> 
> \-s 指定该参数表示不覆盖已经存在的文件
> 
> \-t 指定模版文件所在目录

生成好的客户端代码  
如图：![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3N1bnJqX25pdQ_size_16_color_FFFFFF_t_70_pic_center 2]  
生成的这些文件里，src文件下的文件和pom.xml文件是对我们最有用的。把它们导入到我们习惯用的java编辑器里，这里以idea为例：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3N1bnJqX25pdQ_size_16_color_FFFFFF_t_70_pic_center 3]  
model中就是我们的实体类  
test也就是测试类。可以进行测试  
api所有的controller层都会有

我们会发现生成的默认包是io.swagger.client.api/module，而我们可能想要自己的包，怎么办呢  
只需要生成代码的时候指定–api-package这个选项就好了。

java -jar swagger-codegen-cli.jar generate -i http://xxxx:8807/static/swagger.json -l java -o  /usr/local/swagger/project --api-package com.xxxx.client  --invoker-package com.xxxx.client.invoker --model-package com.xxxx.client.model

# Openapi Generator #

注意：安装Openapi Generator必须安装nodejs

## 一、Openapi Generator的安装 ##

npm install @openapitools/openapi-generator-cli -g

npm install @openapitools/openapi-generator-cli@cli-4.3.1 -g

npm install @openapitools/openapi-generator-cli -D

petstore.yaml上一份json文件，类似于swagger生成的json文件，最下边有复制一份，有需要可直接复制，或者用自己的json文件也可以

npx @openapitools/openapi-generator-cli generate -i petstore.yaml -g java  -o /tmp/test/

\-i指定要生成的json的文件的路径  
\-o文件导出的路径  
\-g指定要生成的语言

然后就完成了

导出的文件：与 swagger-codegen是一样的

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3N1bnJqX25pdQ_size_16_color_FFFFFF_t_70_pic_center 4]  
导入idea进行测试就可以了

## petstore.yaml文件 ##

swagger: '2.0'
    info:
      description: 'This is a sample server Petstore server. For this sample, you can use the api key `special-key` to test the authorization filters.'
      version: 1.0.0
      title: OpenAPI Petstore
      license:
        name: Apache-2.0
        url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
    host: petstore.swagger.io
    basePath: /v2
    tags:
      - name: pet
        description: Everything about your Pets
      - name: store
        description: Access to Petstore orders
      - name: user
        description: Operations about user
    schemes:
      - http
    paths:
      /pet:
        post:
          tags:
            - pet
          summary: Add a new pet to the store
          description: ''
          operationId: addPet
          consumes:
            - application/json
            - application/xml
          produces:
            - application/xml
            - application/json
          parameters:
            - in: body
              name: body
              description: Pet object that needs to be added to the store
              required: true
              schema:
                $ref: '#/definitions/Pet'
          responses:
            '405':
              description: Invalid input
          security:
            - petstore_auth:
                - 'write:pets'
                - 'read:pets'
        put:
          tags:
            - pet
          summary: Update an existing pet
          description: ''
          operationId: updatePet
          consumes:
            - application/json
            - application/xml
          produces:
            - application/xml
            - application/json
          parameters:
            - in: body
              name: body
              description: Pet object that needs to be added to the store
              required: true
              schema:
                $ref: '#/definitions/Pet'
          responses:
            '400':
              description: Invalid ID supplied
            '404':
              description: Pet not found
            '405':
              description: Validation exception
          security:
            - petstore_auth:
                - 'write:pets'
                - 'read:pets'
      /pet/findByStatus:
        get:
          tags:
            - pet
          summary: Finds Pets by status
          description: Multiple status values can be provided with comma separated strings
          operationId: findPetsByStatus
          produces:
            - application/xml
            - application/json
          parameters:
            - name: status
              in: query
              description: Status values that need to be considered for filter
              required: true
              type: array
              items:
                type: string
                enum:
                  - available
                  - pending
                  - sold
                default: available
              collectionFormat: csv
          responses:
            '200':
              description: successful operation
              schema:
                type: array
                items:
                  $ref: '#/definitions/Pet'
            '400':
              description: Invalid status value
          security:
            - petstore_auth:
                - 'write:pets'
                - 'read:pets'
      /pet/findByTags:
        get:
          tags:
            - pet
          summary: Finds Pets by tags
          description: 'Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.'
          operationId: findPetsByTags
          produces:
            - application/xml
            - application/json
          parameters:
            - name: tags
              in: query
              description: Tags to filter by
              required: true
              type: array
              items:
                type: string
              collectionFormat: csv
          responses:
            '200':
              description: successful operation
              schema:
                type: array
                items:
                  $ref: '#/definitions/Pet'
            '400':
              description: Invalid tag value
          security:
            - petstore_auth:
                - 'write:pets'
                - 'read:pets'
          deprecated: true
      '/pet/{petId}':
        get:
          tags:
            - pet
          summary: Find pet by ID
          description: Returns a single pet
          operationId: getPetById
          produces:
            - application/xml
            - application/json
          parameters:
            - name: petId
              in: path
              description: ID of pet to return
              required: true
              type: integer
              format: int64
          responses:
            '200':
              description: successful operation
              schema:
                $ref: '#/definitions/Pet'
            '400':
              description: Invalid ID supplied
            '404':
              description: Pet not found
          security:
            - api_key: []
        post:
          tags:
            - pet
          summary: Updates a pet in the store with form data
          description: ''
          operationId: updatePetWithForm
          consumes:
            - application/x-www-form-urlencoded
          produces:
            - application/xml
            - application/json
          parameters:
            - name: petId
              in: path
              description: ID of pet that needs to be updated
              required: true
              type: integer
              format: int64
            - name: name
              in: formData
              description: Updated name of the pet
              required: false
              type: string
            - name: status
              in: formData
              description: Updated status of the pet
              required: false
              type: string
          responses:
            '405':
              description: Invalid input
          security:
            - petstore_auth:
                - 'write:pets'
                - 'read:pets'
        delete:
          tags:
            - pet
          summary: Deletes a pet
          description: ''
          operationId: deletePet
          produces:
            - application/xml
            - application/json
          parameters:
            - name: api_key
              in: header
              required: false
              type: string
            - name: petId
              in: path
              description: Pet id to delete
              required: true
              type: integer
              format: int64
          responses:
            '400':
              description: Invalid pet value
          security:
            - petstore_auth:
                - 'write:pets'
                - 'read:pets'
      '/pet/{petId}/uploadImage':
        post:
          tags:
            - pet
          summary: uploads an image
          description: ''
          operationId: uploadFile
          consumes:
            - multipart/form-data
          produces:
            - application/json
          parameters:
            - name: petId
              in: path
              description: ID of pet to update
              required: true
              type: integer
              format: int64
            - name: additionalMetadata
              in: formData
              description: Additional data to pass to server
              required: false
              type: string
            - name: file
              in: formData
              description: file to upload
              required: false
              type: file
          responses:
            '200':
              description: successful operation
              schema:
                $ref: '#/definitions/ApiResponse'
          security:
            - petstore_auth:
                - 'write:pets'
                - 'read:pets'
      /store/inventory:
        get:
          tags:
            - store
          summary: Returns pet inventories by status
          description: Returns a map of status codes to quantities
          operationId: getInventory
          produces:
            - application/json
          parameters: []
          responses:
            '200':
              description: successful operation
              schema:
                type: object
                additionalProperties:
                  type: integer
                  format: int32
          security:
            - api_key: []
      /store/order:
        post:
          tags:
            - store
          summary: Place an order for a pet
          description: ''
          operationId: placeOrder
          produces:
            - application/xml
            - application/json
          parameters:
            - in: body
              name: body
              description: order placed for purchasing the pet
              required: true
              schema:
                $ref: '#/definitions/Order'
          responses:
            '200':
              description: successful operation
              schema:
                $ref: '#/definitions/Order'
            '400':
              description: Invalid Order
      '/store/order/{orderId}':
        get:
          tags:
            - store
          summary: Find purchase order by ID
          description: 'For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions'
          operationId: getOrderById
          produces:
            - application/xml
            - application/json
          parameters:
            - name: orderId
              in: path
              description: ID of pet that needs to be fetched
              required: true
              type: integer
              maximum: 5
              minimum: 1
              format: int64
          responses:
            '200':
              description: successful operation
              schema:
                $ref: '#/definitions/Order'
            '400':
              description: Invalid ID supplied
            '404':
              description: Order not found
        delete:
          tags:
            - store
          summary: Delete purchase order by ID
          description: For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors
          operationId: deleteOrder
          produces:
            - application/xml
            - application/json
          parameters:
            - name: orderId
              in: path
              description: ID of the order that needs to be deleted
              required: true
              type: string
          responses:
            '400':
              description: Invalid ID supplied
            '404':
              description: Order not found
      /user:
        post:
          tags:
            - user
          summary: Create user
          description: This can only be done by the logged in user.
          operationId: createUser
          produces:
            - application/xml
            - application/json
          parameters:
            - in: body
              name: body
              description: Created user object
              required: true
              schema:
                $ref: '#/definitions/User'
          responses:
            default:
              description: successful operation
      /user/createWithArray:
        post:
          tags:
            - user
          summary: Creates list of users with given input array
          description: ''
          operationId: createUsersWithArrayInput
          produces:
            - application/xml
            - application/json
          parameters:
            - in: body
              name: body
              description: List of user object
              required: true
              schema:
                type: array
                items:
                  $ref: '#/definitions/User'
          responses:
            default:
              description: successful operation
      /user/createWithList:
        post:
          tags:
            - user
          summary: Creates list of users with given input array
          description: ''
          operationId: createUsersWithListInput
          produces:
            - application/xml
            - application/json
          parameters:
            - in: body
              name: body
              description: List of user object
              required: true
              schema:
                type: array
                items:
                  $ref: '#/definitions/User'
          responses:
            default:
              description: successful operation
      /user/login:
        get:
          tags:
            - user
          summary: Logs user into the system
          description: ''
          operationId: loginUser
          produces:
            - application/xml
            - application/json
          parameters:
            - name: username
              in: query
              description: The user name for login
              required: true
              type: string
            - name: password
              in: query
              description: The password for login in clear text
              required: true
              type: string
          responses:
            '200':
              description: successful operation
              schema:
                type: string
              headers:
                X-Rate-Limit:
                  type: integer
                  format: int32
                  description: calls per hour allowed by the user
                X-Expires-After:
                  type: string
                  format: date-time
                  description: date in UTC when toekn expires
            '400':
              description: Invalid username/password supplied
      /user/logout:
        get:
          tags:
            - user
          summary: Logs out current logged in user session
          description: ''
          operationId: logoutUser
          produces:
            - application/xml
            - application/json
          parameters: []
          responses:
            default:
              description: successful operation
      '/user/{username}':
        get:
          tags:
            - user
          summary: Get user by user name
          description: ''
          operationId: getUserByName
          produces:
            - application/xml
            - application/json
          parameters:
            - name: username
              in: path
              description: 'The name that needs to be fetched. Use user1 for testing.'
              required: true
              type: string
          responses:
            '200':
              description: successful operation
              schema:
                $ref: '#/definitions/User'
            '400':
              description: Invalid username supplied
            '404':
              description: User not found
        put:
          tags:
            - user
          summary: Updated user
          description: This can only be done by the logged in user.
          operationId: updateUser
          produces:
            - application/xml
            - application/json
          parameters:
            - name: username
              in: path
              description: name that need to be deleted
              required: true
              type: string
            - in: body
              name: body
              description: Updated user object
              required: true
              schema:
                $ref: '#/definitions/User'
          responses:
            '400':
              description: Invalid user supplied
            '404':
              description: User not found
        delete:
          tags:
            - user
          summary: Delete user
          description: This can only be done by the logged in user.
          operationId: deleteUser
          produces:
            - application/xml
            - application/json
          parameters:
            - name: username
              in: path
              description: The name that needs to be deleted
              required: true
              type: string
          responses:
            '400':
              description: Invalid username supplied
            '404':
              description: User not found
    securityDefinitions:
      petstore_auth:
        type: oauth2
        authorizationUrl: 'http://petstore.swagger.io/api/oauth/dialog'
        flow: implicit
        scopes:
          'write:pets': modify pets in your account
          'read:pets': read your pets
      api_key:
        type: apiKey
        name: api_key
        in: header
    definitions:
      Order:
        title: Pet Order
        description: An order for a pets from the pet store
        type: object
        properties:
          id:
            type: integer
            format: int64
          petId:
            type: integer
            format: int64
          quantity:
            type: integer
            format: int32
          shipDate:
            type: string
            format: date-time
          status:
            type: string
            description: Order Status
            enum:
              - placed
              - approved
              - delivered
          complete:
            type: boolean
            default: false
        xml:
          name: Order
      Category:
        title: Pet category
        description: A category for a pet
        type: object
        properties:
          id:
            type: integer
            format: int64
          name:
            type: string
        xml:
          name: Category
      User:
        title: a User
        description: A User who is purchasing from the pet store
        type: object
        properties:
          id:
            type: integer
            format: int64
          username:
            type: string
          firstName:
            type: string
          lastName:
            type: string
          email:
            type: string
          password:
            type: string
          phone:
            type: string
          userStatus:
            type: integer
            format: int32
            description: User Status
        xml:
          name: User
      Tag:
        title: Pet Tag
        description: A tag for a pet
        type: object
        properties:
          id:
            type: integer
            format: int64
          name:
            type: string
        xml:
          name: Tag
      Pet:
        title: a Pet
        description: A pet for sale in the pet store
        type: object
        required:
          - name
          - photoUrls
        properties:
          id:
            type: integer
            format: int64
          category:
            $ref: '#/definitions/Category'
          name:
            type: string
            example: doggie
          photoUrls:
            type: array
            xml:
              name: photoUrl
              wrapped: true
            items:
              type: string
          tags:
            type: array
            xml:
              name: tag
              wrapped: true
            items:
              $ref: '#/definitions/Tag'
          status:
            type: string
            description: pet status in the store
            enum:
              - available
              - pending
              - sold
        xml:
          name: Pet
      ApiResponse:
        title: An uploaded response
        description: Describes the result of uploading an image resource
        type: object
        properties:
          code:
            type: integer
            format: int32
          type:
            type: string
          message:
            type: string

[https_github.com_swagger-api_swagger-codegen]: https://github.com/swagger-api/swagger-codegen
[https_www.jianshu.com_p_14a35d6f7b1a]: https://www.jianshu.com/p/14a35d6f7b1a
[https_www.cnblogs.com_shamo89_p_7680771.html]: https://www.cnblogs.com/shamo89/p/7680771.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3N1bnJqX25pdQ_size_16_color_FFFFFF_t_70_pic_center]: /images/20210913/b09ab7e115c24065984be712307a4d77.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3N1bnJqX25pdQ_size_16_color_FFFFFF_t_70_pic_center 1]: /images/20210913/c20f450867c641bf824ba4b6305d5913.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3N1bnJqX25pdQ_size_16_color_FFFFFF_t_70_pic_center 2]: /images/20210913/7c4712f21f3142659f515393828ef3af.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3N1bnJqX25pdQ_size_16_color_FFFFFF_t_70_pic_center 3]: /images/20210913/cf02405518d54eb9bc28fa8f0942634d.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3N1bnJqX25pdQ_size_16_color_FFFFFF_t_70_pic_center 4]: /images/20210913/580f3db637994c4ba0ab114529601ba5.png