What is an OpenAPI Specification?

OpenAPI is a standard for documenting REST APIs

The OpenAPI Specification (OAS) is a framework used by developers to document REST APIs. The specification written in JSON or YAML and contains all of your endpoints, parameters, schemas, and authentication schemes.

Considering options to generate an OpenAPI spec? Get live support here

Below is an example of an OpenAPI file:

openapi.yml
1openapi: 3.0.2

2info:

3  title: Petstore - OpenAPI 3.0

4  description: |-

5    This is a sample Pet Store Server based on the OpenAPI 3.0 specification.

6paths:

7  "/pet":

8    put:

9      tags:

10      - pet

11      summary: Update an existing pet

12      description: Update an existing pet by Id

13      operationId: updatePet

14      requestBody:

15        description: Update an existent pet in the store

16        content:

17          application/json:

18            schema:

19              "$ref": "#/components/schemas/Pet"

20        required: true

21      responses:

22        '200':

23          description: Successful operation

24          content:

25            application/json:

26              schema:

27                "$ref": "#/components/schemas/Pet"

28        '400':

29          description: Invalid ID supplied

30        '404':

31          description: Pet not found

32        '405':

33          description: Validation exception

34      security:

35      - api_key

36components:

37  schemas:

38    Category:

39      type: object

40      properties:

41        id:

42          type: integer

43          format: int64

44          example: 1

45        name:

46          type: string

47          example: Dogs

48    Tag:

49      type: object

50      properties:

51        id:

52          type: integer

53          format: int64

54        name:

55          type: string

56    Pet:

57      required:

58      - name

59      - photoUrls

60      type: object

61      properties:

62        id:

63          type: integer

64          format: int64

65          example: 10

66        name:

67          type: string

68          example: doggie

69        category:

70          "$ref": "#/components/schemas/Category"

71        photoUrls:

72          type: array

73          items:

74            type: string

75        tags:

76          type: array

77          items:

78            "$ref": "#/components/schemas/Tag"

79        status:

80          type: string

81          description: pet status in the store

82          enum:

83          - available

84          - pending

85          - sold

86  securitySchemes:

87    api_key:

88      type: apiKey

89      name: api_key

90      in: header

Setup your Fern folder

Start by initializing your Fern folder with an OpenAPI spec

1fern init --openapi ./path/to/openapi

This will initialize a directory like the following

fern/

  ├─ fern.config.json

  ├─ generators.yml

  └─ openapi/

    ├─ openapi.yml