代码优先还是设计优先？说说API开发技术（七）

生成服务器代码

生成Spring服务器

openapi-generator generate -i ./petstore.yaml -g spring -o out/server/springboot 

UserController.java

package org.openapitools.api;

 

import org.springframework.stereotype.Controller;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.context.request.NativeWebRequest;

import java.util.Optional;

@javax.annotation.Generated(value = "org.openapitools.codegen.languages.SpringCodegen", date = "2020-04-30T14:18:18.784-07:00[America/Los_Angeles]")

 

@Controller

@RequestMapping("${openapi.openAPIPetstore.base-path:/v2}")

public class UserApiController implements UserApi {

 

    private final NativeWebRequest request;

 

    @org.springframework.beans.factory.annotation.Autowired

    public UserApiController(NativeWebRequest request) {

        this.request = request;

    }

 

    @Override

    public Optional<NativeWebRequest> getRequest() {

        return Optional.ofNullable(request);

    }

 

}

UserApi.java

/**

 * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech) (4.3.0).

 * https://openapi-generator.tech

 * Do not edit the class manually.

 */

package org.openapitools.api;

 

import java.util.List;

import org.openapitools.model.User;

import io.swagger.annotations.*;

import org.springframework.http.HttpStatus;

import org.springframework.http.MediaType;

import org.springframework.http.ResponseEntity;

import org.springframework.validation.annotation.Validated;

import org.springframework.web.bind.annotation.CookieValue;

import org.springframework.web.bind.annotation.PathVariable;

import org.springframework.web.bind.annotation.RequestBody;

import org.springframework.web.bind.annotation.RequestHeader;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RequestMethod;

import org.springframework.web.bind.annotation.RequestParam;

import org.springframework.web.bind.annotation.RequestPart;

import org.springframework.web.context.request.NativeWebRequest;

import org.springframework.web.multipart.MultipartFile;

 

import javax.validation.Valid;

import javax.validation.constraints.*;

import java.util.List;

import java.util.Map;

import java.util.Optional;

@javax.annotation.Generated(value = "org.openapitools.codegen.languages.SpringCodegen", date = "2020-04-30T14:18:18.784-07:00[America/Los_Angeles]")

 

@Validated

@Api(value = "user", description = "the user API")

public interface UserApi {

 

    default Optional<NativeWebRequest> getRequest() {

        return Optional.empty();

    }

 

    /**

     * POST /user : Create user

     * This can only be done by the logged in user.

     *

     * @param body Created user object (required)

     * @return successful operation (status code 200)

     */

    @ApiOperation(value = "Create user", nickname = "createUser", notes = "This can only be done by the logged in user.", tags={ "user", })

    @ApiResponses(value = { 

        @ApiResponse(code = 200, message = "successful operation") })

    @RequestMapping(value = "/user",

        method = RequestMethod.POST)

    default ResponseEntity<Void> createUser(@ApiParam(value = "Created user object" ,required=true )  @Valid @RequestBody User body) {

        return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);

 

    }

    /**

     * POST /user/createWithArray : Creates list of users with given input array

     *

     * @param body List of user object (required)

     * @return successful operation (status code 200)

     */

    @ApiOperation(value = "Creates list of users with given input array", nickname = "createUsersWithArrayInput", notes = "", tags={ "user", })

    @ApiResponses(value = { 

        @ApiResponse(code = 200, message = "successful operation") })

    @RequestMapping(value = "/user/createWithArray",

        method = RequestMethod.POST)

    default ResponseEntity<Void> createUsersWithArrayInput(@ApiParam(value = "List of user object" ,required=true )  @Valid @RequestBody List<User> body) {

        return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);

 

    }

   /**

     * POST /user/createWithList : Creates list of users with given input array

     *

     * @param body List of user object (required)

     * @return successful operation (status code 200)

     */

    @ApiOperation(value = "Creates list of users with given input array", nickname = "createUsersWithListInput", notes = "", tags={ "user", })

    @ApiResponses(value = { 

        @ApiResponse(code = 200, message = "successful operation") })

    @RequestMapping(value = "/user/createWithList",

        method = RequestMethod.POST)

    default ResponseEntity<Void> createUsersWithListInput(@ApiParam(value = "List of user object" ,required=true )  @Valid @RequestBody List<User> body) {

        return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);

 

    }

    /**

     * DELETE /user/{username} : Delete user

     * This can only be done by the logged in user.

     *

     * @param username The name that needs to be deleted (required)

     * @return Invalid username supplied (status code 400)

     *         or User not found (status code 404)

     */

    @ApiOperation(value = "Delete user", nickname = "deleteUser", notes = "This can only be done by the logged in user.", tags={ "user", })

    @ApiResponses(value = { 

        @ApiResponse(code = 400, message = "Invalid username supplied"),

        @ApiResponse(code = 404, message = "User not found") })

    @RequestMapping(value = "/user/{username}",

        method = RequestMethod.DELETE)

    default ResponseEntity<Void> deleteUser(@ApiParam(value = "The name that needs to be deleted",required=true) @PathVariable("username") String username) {

        return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);

 

    }

/**

     * GET /user/{username} : Get user by user name

     *

     * @param username The name that needs to be fetched. Use user1 for testing. (required)

     * @return successful operation (status code 200)

     *         or Invalid username supplied (status code 400)

     *         or User not found (status code 404)

     */

    @ApiOperation(value = "Get user by user name", nickname = "getUserByName", notes = "", response = User.class, tags={ "user", })

    @ApiResponses(value = { 

        @ApiResponse(code = 200, message = "successful operation", response = User.class),

        @ApiResponse(code = 400, message = "Invalid username supplied"),

        @ApiResponse(code = 404, message = "User not found") })

    @RequestMapping(value = "/user/{username}",

        produces = { "application/xml", "application/json" }, 

        method = RequestMethod.GET)

    default ResponseEntity<User> getUserByName(@ApiParam(value = "The name that needs to be fetched. Use user1 for testing.",required=true) @PathVariable("username") String username) {

        getRequest().ifPresent(request -> {

            for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {

                if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {

                    String exampleString = "{ \"firstName\" : \"firstName\", \"lastName\" : \"lastName\", \"password\" : \"password\", \"userStatus\" : 6, \"phone\" : \"phone\", \"id\" : 0, \"email\" : \"email\", \"username\" : \"username\" }";

                    ApiUtil.setExampleResponse(request, "application/json", exampleString);

                    break;

                }

                if (mediaType.isCompatibleWith(MediaType.valueOf("application/xml"))) {

                    String exampleString = "<User> <id>123456789</id> <username>aeiou</username> <firstName>aeiou</firstName> <lastName>aeiou</lastName> <email>aeiou</email> <password>aeiou</password> <phone>aeiou</phone> <userStatus>123</userStatus> </User>";

                    ApiUtil.setExampleResponse(request, "application/xml", exampleString);

                    break;

                }

            }

        });

        return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);

 

    }

    /**

     * GET /user/login : Logs user into the system

     *

     * @param username The user name for login (required)

     * @param password The password for login in clear text (required)

     * @return successful operation (status code 200)

     *         or Invalid username/password supplied (status code 400)

     */

    @ApiOperation(value = "Logs user into the system", nickname = "loginUser", notes = "", response = String.class, tags={ "user", })

    @ApiResponses(value = { 

        @ApiResponse(code = 200, message = "successful operation", response = String.class),

        @ApiResponse(code = 400, message = "Invalid username/password supplied") })

    @RequestMapping(value = "/user/login",

        produces = { "application/xml", "application/json" }, 

        method = RequestMethod.GET)

    default ResponseEntity<String> loginUser(@NotNull @ApiParam(value = "The user name for login", required = true) @Valid @RequestParam(value = "username", required = true) String username,@NotNull @ApiParam(value = "The password for login in clear text", required = true) @Valid @RequestParam(value = "password", required = true) String password) {

        return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);

 

    }

   /**

     * GET /user/logout : Logs out current logged in user session

     *

     * @return successful operation (status code 200)

     */

    @ApiOperation(value = "Logs out current logged in user session", nickname = "logoutUser", notes = "", tags={ "user", })

    @ApiResponses(value = { 

        @ApiResponse(code = 200, message = "successful operation") })

    @RequestMapping(value = "/user/logout",

        method = RequestMethod.GET)

    default ResponseEntity<Void> logoutUser() {

        return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);

 

    }

    /**

     * PUT /user/{username} : Updated user

     * This can only be done by the logged in user.

     *

     * @param username name that need to be deleted (required)

     * @param body Updated user object (required)

     * @return Invalid user supplied (status code 400)

     *         or User not found (status code 404)

     */

    @ApiOperation(value = "Updated user", nickname = "updateUser", notes = "This can only be done by the logged in user.", tags={ "user", })

    @ApiResponses(value = { 

        @ApiResponse(code = 400, message = "Invalid user supplied"),

        @ApiResponse(code = 404, message = "User not found") })

    @RequestMapping(value = "/user/{username}",

        method = RequestMethod.PUT)

    default ResponseEntity<Void> updateUser(@ApiParam(value = "name that need to be deleted",required=true) @PathVariable("username") String username,@ApiParam(value = "Updated user object" ,required=true )  @Valid @RequestBody User body) {

        return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);

 

    }

 

}

 

生成Golang服务器

openapi-generator generate -i ./petstore.yaml -g go-server -o out/server/go-server 

main.go

/*

 * OpenAPI Petstore

 *

 * This is a sample server Petstore server. For this sample, you can use the api key `special-key` to test the authorization filters.

 *

 * API version: 1.0.0

 * Generated by: OpenAPI Generator (https://openapi-generator.tech)

 */

 

package main

 

import (

    "log"

    "net/http"

 

    openapi "github.com/GIT_USER_ID/GIT_REPO_ID/go"

)

 

func main() {

    log.Printf("Server started")

 

    PetApiService := openapi.NewPetApiService()

    PetApiController := openapi.NewPetApiController(PetApiService)

 

    StoreApiService := openapi.NewStoreApiService()

    StoreApiController := openapi.NewStoreApiController(StoreApiService)

 

    UserApiService := openapi.NewUserApiService()

    UserApiController := openapi.NewUserApiController(UserApiService)

 

    router := openapi.NewRouter(PetApiController, StoreApiController, UserApiController)

 

    log.Fatal(http.ListenAndServe(":8080", router))

}

 

api.go

/*

 * OpenAPI Petstore

 *

 * This is a sample server Petstore server. For this sample, you can use the api key `special-key` to test the authorization filters.

 *

 * API version: 1.0.0

 * Generated by: OpenAPI Generator (https://openapi-generator.tech)

 */

 

package openapi

 

import (

    "net/http"

    "os"

)

 

// PetApiRouter defines the required methods for binding the api requests to a responses for the PetApi

// The PetApiRouter implementation should parse necessary information from the http request, 

// pass the data to a PetApiServicer to perform the required actions, then write the service results to the http response.

type PetApiRouter interface { 

    AddPet(http.ResponseWriter, *http.Request)

    DeletePet(http.ResponseWriter, *http.Request)

    FindPetsByStatus(http.ResponseWriter, *http.Request)

    FindPetsByTags(http.ResponseWriter, *http.Request)

    GetPetById(http.ResponseWriter, *http.Request)

    UpdatePet(http.ResponseWriter, *http.Request)

    UpdatePetWithForm(http.ResponseWriter, *http.Request)

    UploadFile(http.ResponseWriter, *http.Request)

}

// StoreApiRouter defines the required methods for binding the api requests to a responses for the StoreApi

// The StoreApiRouter implementation should parse necessary information from the http request, 

// pass the data to a StoreApiServicer to perform the required actions, then write the service results to the http response.

type StoreApiRouter interface { 

    DeleteOrder(http.ResponseWriter, *http.Request)

    GetInventory(http.ResponseWriter, *http.Request)

    GetOrderById(http.ResponseWriter, *http.Request)

    PlaceOrder(http.ResponseWriter, *http.Request)

}

// UserApiRouter defines the required methods for binding the api requests to a responses for the UserApi

// The UserApiRouter implementation should parse necessary information from the http request, 

// pass the data to a UserApiServicer to perform the required actions, then write the service results to the http response.

type UserApiRouter interface { 

    CreateUser(http.ResponseWriter, *http.Request)

    CreateUsersWithArrayInput(http.ResponseWriter, *http.Request)

    CreateUsersWithListInput(http.ResponseWriter, *http.Request)

    DeleteUser(http.ResponseWriter, *http.Request)

    GetUserByName(http.ResponseWriter, *http.Request)

    LoginUser(http.ResponseWriter, *http.Request)

    LogoutUser(http.ResponseWriter, *http.Request)

    UpdateUser(http.ResponseWriter, *http.Request)

}

// PetApiServicer defines the api actions for the PetApi service

// This interface intended to stay up to date with the openapi yaml used to generate it, 

// while the service implementation can ignored with the .openapi-generator-ignore file 

// and updated with the logic required for the API.

type PetApiServicer interface { 

    AddPet(Pet) (interface{}, error)

    DeletePet(int64, string) (interface{}, error)

    FindPetsByStatus([]string) (interface{}, error)

    FindPetsByTags([]string) (interface{}, error)

    GetPetById(int64) (interface{}, error)

    UpdatePet(Pet) (interface{}, error)

    UpdatePetWithForm(int64, string, string) (interface{}, error)

    UploadFile(int64, string, *os.File) (interface{}, error)

}

// StoreApiServicer defines the api actions for the StoreApi service

// This interface intended to stay up to date with the openapi yaml used to generate it, 

// while the service implementation can ignored with the .openapi-generator-ignore file 

// and updated with the logic required for the API.

type StoreApiServicer interface { 

    DeleteOrder(string) (interface{}, error)

    GetInventory() (interface{}, error)

    GetOrderById(int64) (interface{}, error)

    PlaceOrder(Order) (interface{}, error)

}

 

// UserApiServicer defines the api actions for the UserApi service

// This interface intended to stay up to date with the openapi yaml used to generate it, 

// while the service implementation can ignored with the .openapi-generator-ignore file 

// and updated with the logic required for the API.

type UserApiServicer interface { 

    CreateUser(User) (interface{}, error)

    CreateUsersWithArrayInput([]User) (interface{}, error)

    CreateUsersWithListInput([]User) (interface{}, error)

    DeleteUser(string) (interface{}, error)

    GetUserByName(string) (interface{}, error)

    LoginUser(string, string) (interface{}, error)

    LogoutUser() (interface{}, error)

    UpdateUser(string, User) (interface{}, error)

}

 

支持的生成器类别

1.       ada

2.       ada-server

3.       android

4.       apache2

5.       apex

6.       aspnetcore

7.       avro-schema

8.       bash

9.       c

10.  clojure

11.  cwiki

12.  cpp-qt5-client

13.  cpp-qt5-qhttpengine-server

14.  cpp-pistache-server

15.  cpp-restbed-server

16.  cpp-restsdk

17.  cpp-tizen

18.  csharp

19.  csharp-netcore

20.  csharp-dotnet2

21.  csharp-nancyfx

22.  dart

23.  dart-dio

24.  dart-jaguar

25.  eiffel

26.  elixir

27.  elm

28.  erlang-client

29.  erlang-proper

30.  erlang-server

31.  flash

32.  fsharp-giraffe-server

33.  go

34.  go-experimental

35.  go-server

36.  go-gin-server

37.  graphql-schema

38.  graphql-nodejs-express-server

39.  groovy

40.  kotlin

41.  kotlin-server

42.  kotlin-spring

43.  kotlin-vertx

44.  haskell-http-client

45.  haskell

46.  java

47.  jaxrs-cxf-client

48.  java-inflector

49.  java-msf4j

50.  java-pkmst

51.  java-play-framework

52.  java-undertow-server

53.  java-vertx

54.  java-vertx-web

55.  jaxrs-cxf

56.  jaxrs-cxf-extended

57.  jaxrs-cxf-cdi

58.  jaxrs-jersey

59.  jaxrs-resteasy

60.  jaxrs-resteasy-eap

61.  jaxrs-spec

62.  javascript

63.  javascript-apollo

64.  javascript-flowtyped

65.  javascript-closure-angular

66.  jmeter

67.  k6

68.  lua

69.  mysql-schema

70.  nim

71.  nodejs-server-deprecated

72.  nodejs-express-server

73.  objc

74.  ocaml

75.  openapi

76.  openapi-yaml

77.  perl

78.  php

79.  php-laravel

80.  php-lumen

81.  php-slim-deprecated

82.  php-slim4

83.  php-silex

84.  php-symfony

85.  php-ze-ph

86.  powershell

87.  powershell-experimental

88.  protobuf-schema

89.  python

90.  python-experimental

91.  python-flask

92.  python-aiohttp

93.  python-blueplanet

94.  r

95.  ruby

96.  ruby-on-rails

97.  ruby-sinatra

98.  rust

99.  rust-server

100.           scalatra

101.           scala-akka

102.           scala-finch

103.           scala-httpclient-deprecated

104.           scala-gatling

105.           scala-lagom-server

106.           scala-play-server

107.           scalaz

108.           spring

109.           dynamic-html

110.           html

111.           html2

112.           swift2-deprecated

113.           swift3-deprecated

114.           swift4

115.           swift5

116.           typescript-angular

117.           typescript-angularjs

118.           typescript-aurelia

119.           typescript-axios

120.           typescript-fetch

121.           typescript-inversify

122.           typescript-jquery

123.           typescript-node

124.           typescript-redux-query

125.           typescript-rxjs

126.           asciidoc

127.           fsharp-functions

128.           markdown

129.           scala-sttp

【代码优先：Swagger UI】

我们来看一下如何从现有的代码生成API文档。

 安装程序库：

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger2</artifactId>

            <version>${swagger.version}</version>

        </dependency>

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger-ui</artifactId>

            <version>${swagger.version}</version>

        </dependency>

        <dependency>

            <groupId>io.swagger</groupId>

            <artifactId>swagger-annotations</artifactId>

            <version>${swagger-annotations.version}</version>

        </dependency>

        <dependency>

            <groupId>io.swagger</groupId>

            <artifactId>swagger-models</artifactId>

            <version>${swagger-models.version}</version>

        </dependency>