OpenAPI Generator の導入

[kinari321]

https://github.com/OpenAPITools/openapi-generator

[kinari321]

~ここで試す~ Swagger Editor で試す

https://editor.swagger.io/

サンプルコード

https://github.com/gothinkster/realworld/blob/main/api/openapi.yml ``` # # Original # https://github.com/gothinkster/realworld/blob/main/api/openapi.yml # openapi: 3.0.1 info: title: Conduit API description: Conduit API documentation contact: name: RealWorld url: https://realworld.how license: name: MIT License url: https://opensource.org/licenses/MIT version: 1.0.0 tags: - name: Articles - name: Comments - name: Favorites - name: Profile - name: Tags - name: User and Authentication servers: - url: /api paths: /users/login: post: tags: - User and Authentication summary: Existing user login description: Login for existing user operationId: Login requestBody: $ref: '#/components/requestBodies/LoginUserRequest' responses: '200': $ref: '#/components/responses/UserResponse' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/GenericError' x-codegen-request-body-name: body /users: post: tags: - User and Authentication description: Register a new user operationId: CreateUser requestBody: $ref: '#/components/requestBodies/NewUserRequest' responses: '201': $ref: '#/components/responses/UserResponse' '422': $ref: '#/components/responses/GenericError' x-codegen-request-body-name: body /user: get: tags: - User and Authentication summary: Get current user description: Gets the currently logged-in user operationId: GetCurrentUser responses: '200': $ref: '#/components/responses/UserResponse' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/GenericError' security: - Token: [] put: tags: - User and Authentication summary: Update current user description: Updated user information for current user operationId: UpdateCurrentUser requestBody: $ref: '#/components/requestBodies/UpdateUserRequest' responses: '200': $ref: '#/components/responses/UserResponse' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/GenericError' security: - Token: [] x-codegen-request-body-name: body /profiles/{username}: get: tags: - Profile summary: Get a profile description: Get a profile of a user of the system. Auth is optional operationId: GetProfileByUsername parameters: - name: username in: path description: Username of the profile to get required: true schema: type: string responses: '200': $ref: '#/components/responses/ProfileResponse' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/GenericError' /profiles/{username}/follow: post: tags: - Profile summary: Follow a user description: Follow a user by username operationId: FollowUserByUsername parameters: - name: username in: path description: Username of the profile you want to follow required: true schema: type: string responses: '200': $ref: '#/components/responses/ProfileResponse' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/GenericError' security: - Token: [] delete: tags: - Profile summary: Unfollow a user description: Unfollow a user by username operationId: UnfollowUserByUsername parameters: - name: username in: path description: Username of the profile you want to unfollow required: true schema: type: string responses: '200': $ref: '#/components/responses/ProfileResponse' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/GenericError' security: - Token: [] /articles/feed: get: tags: - Articles summary: Get recent articles from users you follow description: Get most recent articles from users you follow. Use query parameters to limit. Auth is required operationId: GetArticlesFeed parameters: - $ref: '#/components/parameters/offsetParam' - $ref: '#/components/parameters/limitParam' responses: '200': $ref: '#/components/responses/MultipleArticlesResponse' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/GenericError' security: - Token: [] /articles: get: tags: - Articles summary: Get recent articles globally description: Get most recent articles globally. Use query parameters to filter results. Auth is optional operationId: GetArticles parameters: - name: tag in: query description: Filter by tag schema: type: string - name: author in: query description: Filter by author (username) schema: type: string - name: favorited in: query description: Filter by favorites of a user (username) schema: type: string - $ref: '#/components/parameters/offsetParam' - $ref: '#/components/parameters/limitParam' responses: '200': $ref: '#/components/responses/MultipleArticlesResponse' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/GenericError' post: tags: - Articles summary: Create an article description: Create an article. Auth is required operationId: CreateArticle requestBody: $ref: '#/components/requestBodies/NewArticleRequest' responses: '201': $ref: '#/components/responses/SingleArticleResponse' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/GenericError' security: - Token: [] x-codegen-request-body-name: article /articles/{slug}: get: tags: - Articles summary: Get an article description: Get an article. Auth not required operationId: GetArticle parameters: - name: slug in: path description: Slug of the article to get required: true schema: type: string responses: '200': $ref: '#/components/responses/SingleArticleResponse' '422': $ref: '#/components/responses/GenericError' put: tags: - Articles summary: Update an article description: Update an article. Auth is required operationId: UpdateArticle parameters: - name: slug in: path description: Slug of the article to update required: true schema: type: string requestBody: $ref: '#/components/requestBodies/UpdateArticleRequest' responses: '200': $ref: '#/components/responses/SingleArticleResponse' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/GenericError' security: - Token: [] x-codegen-request-body-name: article delete: tags: - Articles summary: Delete an article description: Delete an article. Auth is required operationId: DeleteArticle parameters: - name: slug in: path description: Slug of the article to delete required: true schema: type: string responses: '200': $ref: '#/components/responses/EmptyOkResponse' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/GenericError' security: - Token: [] /articles/{slug}/comments: get: tags: - Comments summary: Get comments for an article description: Get the comments for an article. Auth is optional operationId: GetArticleComments parameters: - name: slug in: path description: Slug of the article that you want to get comments for required: true schema: type: string responses: '200': $ref: '#/components/responses/MultipleCommentsResponse' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/GenericError' post: tags: - Comments summary: Create a comment for an article description: Create a comment for an article. Auth is required operationId: CreateArticleComment parameters: - name: slug in: path description: Slug of the article that you want to create a comment for required: true schema: type: string requestBody: $ref: '#/components/requestBodies/NewCommentRequest' responses: '200': $ref: '#/components/responses/SingleCommentResponse' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/GenericError' security: - Token: [] x-codegen-request-body-name: comment /articles/{slug}/comments/{id}: delete: tags: - Comments summary: Delete a comment for an article description: Delete a comment for an article. Auth is required operationId: DeleteArticleComment parameters: - name: slug in: path description: Slug of the article that you want to delete a comment for required: true schema: type: string - name: id in: path description: ID of the comment you want to delete required: true schema: type: integer responses: '200': $ref: '#/components/responses/EmptyOkResponse' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/GenericError' security: - Token: [] /articles/{slug}/favorite: post: tags: - Favorites summary: Favorite an article description: Favorite an article. Auth is required operationId: CreateArticleFavorite parameters: - name: slug in: path description: Slug of the article that you want to favorite required: true schema: type: string responses: '200': $ref: '#/components/responses/SingleArticleResponse' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/GenericError' security: - Token: [] delete: tags: - Favorites summary: Unfavorite an article description: Unfavorite an article. Auth is required operationId: DeleteArticleFavorite parameters: - name: slug in: path description: Slug of the article that you want to unfavorite required: true schema: type: string responses: '200': $ref: '#/components/responses/SingleArticleResponse' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/GenericError' security: - Token: [] /tags: get: tags: - Tags summary: Get tags description: Get tags. Auth not required operationId: GetTags responses: '200': $ref: '#/components/responses/TagsResponse' '422': $ref: '#/components/responses/GenericError' components: schemas: LoginUser: required: - email - password type: object properties: email: type: string password: type: string format: password NewUser: required: - email - password - username type: object properties: username: type: string email: type: string password: type: string format: password User: required: - bio - email - image - token - username type: object properties: email: type: string token: type: string username: type: string bio: type: string image: type: string UpdateUser: type: object properties: email: type: string password: type: string username: type: string bio: type: string image: type: string Profile: required: - bio - following - image - username type: object properties: username: type: string bio: type: string image: type: string following: type: boolean Article: required: - author - body - createdAt - description - favorited - favoritesCount - slug - tagList - title - updatedAt type: object properties: slug: type: string title: type: string description: type: string body: type: string tagList: type: array items: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time favorited: type: boolean favoritesCount: type: integer author: $ref: '#/components/schemas/Profile' NewArticle: required: - body - description - title type: object properties: title: type: string description: type: string body: type: string tagList: type: array items: type: string UpdateArticle: type: object properties: title: type: string description: type: string body: type: string Comment: required: - author - body - createdAt - id - updatedAt type: object properties: id: type: integer createdAt: type: string format: date-time updatedAt: type: string format: date-time body: type: string author: $ref: '#/components/schemas/Profile' NewComment: required: - body type: object properties: body: type: string GenericErrorModel: required: - errors type: object properties: errors: required: - body type: object properties: body: type: array items: type: string responses: TagsResponse: description: Tags content: application/json: schema: required: - tags type: object properties: tags: type: array items: type: string SingleCommentResponse: description: Single comment content: application/json: schema: required: - comment type: object properties: comment: $ref: '#/components/schemas/Comment' MultipleCommentsResponse: description: Multiple comments content: application/json: schema: required: - comments type: object properties: comments: type: array items: $ref: '#/components/schemas/Comment' SingleArticleResponse: description: Single article content: application/json: schema: required: - article type: object properties: article: $ref: '#/components/schemas/Article' MultipleArticlesResponse: description: Multiple articles content: application/json: schema: required: - articles - articlesCount type: object properties: articles: type: array items: $ref: '#/components/schemas/Article' articlesCount: type: integer ProfileResponse: description: Profile content: application/json: schema: required: - profile type: object properties: profile: $ref: '#/components/schemas/Profile' UserResponse: description: User content: application/json: schema: required: - user type: object properties: user: $ref: '#/components/schemas/User' EmptyOkResponse: description: No content content: {} Unauthorized: description: Unauthorized content: {} GenericError: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/GenericErrorModel' requestBodies: LoginUserRequest: required: true description: Credentials to use content: application/json: schema: required: - user type: object properties: user: $ref: '#/components/schemas/LoginUser' NewUserRequest: required: true description: Details of the new user to register content: application/json: schema: required: - user type: object properties: user: $ref: '#/components/schemas/NewUser' UpdateUserRequest: required: true description: User details to update. At least **one** field is required. content: application/json: schema: required: - user type: object properties: user: $ref: '#/components/schemas/UpdateUser' NewArticleRequest: required: true description: Article to create content: application/json: schema: required: - article type: object properties: article: $ref: '#/components/schemas/NewArticle' UpdateArticleRequest: required: true description: Article to update content: application/json: schema: required: - article type: object properties: article: $ref: '#/components/schemas/UpdateArticle' NewCommentRequest: required: true description: Comment you want to create content: application/json: schema: required: - comment type: object properties: comment: $ref: '#/components/schemas/NewComment' parameters: offsetParam: in: query name: offset required: false schema: type: integer minimum: 0 description: The number of items to skip before starting to collect the result set. limitParam: in: query name: limit required: false schema: type: integer minimum: 1 default: 20 description: The numbers of items to return. securitySchemes: Token: type: apiKey description: "For accessing the protected API resources, you must have received\ \ a a valid JWT token after registering or logging in. This JWT token must\ \ then be used for all protected resources by passing it in via the 'Authorization'\ \ header.\n\nA JWT token is generated by the API by either registering via\ \ /users or logging in via /users/login.\n\nThe following format must be in\ \ the 'Authorization' header :\n\n Token xxxxxx.yyyyyyy.zzzzzz\n \n" name: Authorization in: header ```

[kinari321]

これをもとに作る

空き家で Go - URL 一覧 - Google スプレッドシート

[kinari321]

参考

realworld-kotlin-springboot-jdbc の OpenAPI

realworld-kotlin-springboot-jdbc/e2e/openapi.yml

[kinari321]

[memo]

参考: OpenAPI Specificationの紹介 - アルファテックブログ

Swagger Editor OpenAPI記述の作成時に利用するツールです。YAMLまたはJSONで記載します。特徴としてSwagger UIとともにブラウザ版が存在し、Swagger UIによってドキュメントを確認しながら作成が可能です。ブラウザ版のアクセス時にサンプルAPIが表示されるので、学習に役立ちます。

Swagger UI OpenAPI記述をビジュアルドキュメントとして表示するオープンソースツールです。Swagger Editorとともにブラウザ版も用意されており、記述をドキュメント化したものを確認することが可能です。ブラウザ版のアクセス時にサンプルAPIが表示されるので、学習に役立ちます。

Swagger Codegen OpenAPI記述からクライアント・サーバーのコードの自動生成をおこなってくれるツールです。C#やC++,Java,Python,Ruby,Typescriptといった様々な言語に対応しています。