Integrate OpenAPI #15

thekid · 2022-04-01T13:39:47Z

Implementation

Using the unpkg CDN, we could simply serve the following from /api:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>SwaggerUI</title>
  <link rel="stylesheet" href="https://unpkg.com/[email protected]/swagger-ui.css" />
</head>
<body style="margin: 0">
  <div id="swagger-ui"></div>
  <script src="https://unpkg.com/[email protected]/swagger-ui-bundle.js" crossorigin></script>
  <script src="https://unpkg.com/[email protected]/swagger-ui-standalone-preset.js" crossorigin></script>
  <script>
    window.onload = () => {
      window.ui = SwaggerUIBundle({
        url: '/api/openapi.json',
        dom_id: '#swagger-ui',
        presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
        layout: 'StandaloneLayout',
      });
    };
  </script>
</body>
</html>

See also https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/installation.md#unpkg

We then need to decide how we want to create the openapi.json file:

Generate from API docs

Use YAML embedded in the api doc comments like https://github.com/Surnet/swagger-jsdoc:

/**
 * @openapi
 * /:
 *   get:
 *     description: Welcome to swagger-jsdoc!
 *     responses:
 *       200:
 *         description: Returns a mysterious string.
 */
app.get('/', (req, res) => {
  res.send('Hello World!');
});

Generate from annotations

Like this example from https://javascript.plainenglish.io/how-to-implement-and-use-swagger-in-nodejs-d0b95e765245:

@Operation(summary = "Sets a price for a chosen car", description = "Returns 202 if successful")
@ApiResponses(
  value = [
      ApiResponse(responseCode = "202", description = "Successful Operation"),
      ApiResponse(responseCode = "404", description = "Such a car does not exist"),
  ]
)
@PostMapping("/price/{carId}", consumes = ["application/json"])
fun setPrice(
  @PathVariable carId: Int,
  @RequestBody @OASRequestBody(
    description = "New price for the car",
    content = [Content(
      mediaType = "application/json",
      schema = Schema(type = "number", format = "float", minimum = "0.0", example = "23000.34"),
    )]
  ) price: BigDecimal
): ResponseEntity<Unit> {
    carService.setPrice(carId, price)
    return ResponseEntity.accepted().build()
}

(Similar to https://zircote.github.io/swagger-php/)

Mixed approach

We can use some of the annotations here:

use web\rest\{Get, Post, Resource, Response};

#[Resource('/users')]
class Users {

  /**
   * Returns all users.
   *
   * - 200: Successful operation
   */
  #[Get('/')]
  public function listUsers($max= 10) {
    // $max comes from request parameter "max", defaulting to 10
    // ...
  }

  /**
   * Returns a given user.
   *
   * - 200: Successful operation
   * - 404: The user cannot be found
   */
  #[Get('/{id}')]
  public function findUser($id) {
    // $id is extracted from URL segment
    // ...
  }

  /**
   * Creates a user.
   *
   * - 201: Successful operation
   * - 400: Validation failed
   */
  #[Post('/')]
  public function createUser($user) {
    // $user is deserialized from the request body according to its content type
    // ...
    return Response::created('/users/{id}', $id)->entity($created);
  }
}

TODO: How do we denote request and response body schemas?

200+UserList: Successful operation and then have UserList defined in the class' api doc?

(Similar to https://vyuldashev.github.io/laravel-openapi/)

The text was updated successfully, but these errors were encountered:

thekid added help wanted Extra attention is needed good first issue Good for newcomers labels Apr 1, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Integrate OpenAPI #15

Integrate OpenAPI #15

thekid commented Apr 1, 2022 •

edited

Loading

Integrate OpenAPI #15

Integrate OpenAPI #15

Comments

thekid commented Apr 1, 2022 • edited Loading

Implementation

Generate from API docs

Generate from annotations

Mixed approach

thekid commented Apr 1, 2022 •

edited

Loading