OpenAPI schema to be generated and placed into docs automatically after each push to master, generated through GitHub Actions.

[0x0elliot]

exactly what the title says. won't do it right now. easy to approach for a DevOps beginner.

Probably have a doc file there which gets automated and a redoc + sphinx service (deployed it here: https://urnode.readthedocs.io/) is automatically deployed off of. The why's and hows can be debated!

[0x0elliot]

Probably set up sphinx in the doc first.

[RoguedBear]

do you want 2 documentations? one for the code generated via sphinx, and the other for the API done via redoc?

[0x0elliot]

one. how IntelOwl does it basically here: https://intelowl.readthedocs.io/

check out their docs.

[0x0elliot]

okay so more context. docs would be/have been set up separately. as far as i understand, a schema.yml is referenced from somewhere. from the API endpoint I have enabled (localhost:8000/openapi) you would be able to fetch the schema. I want it to be dumped automatically to the doc folder and then referenced off of rather than manual updation.

can we pull this off using GitHub actions triggered after each merge to master @RoguedBear ?

[RoguedBear]

fetching the schema from the API endpoint and then dumping it to the docs folder can be done via actions. Is there anything else in the documentation aspect you want to automate?

[0x0elliot]

not anything i can think of other than making sure that redoc with sphinx picks it up automatically and the older schema.yml is deleted.

[0x0elliot]

if that's too hard, we can instead do something like this: https://intelowl.readthedocs.io/en/latest/Contribute.html#note-about-documentation using something like spectacular

it's wayyy more elegant.

[RoguedBear]

now that you've mentioned how IntelOwl does it, I'll be trying 3 approaches and see what works best

• manually generating schema via django cli (without using spectacular)
• getting the schema from the /openapi endpoint
• django cli using spectacular as it says on their docs

[0x0elliot]

whatever is the easier one. maybe spectacular would be able to dump it simply in CI mode.

[RoguedBear]

so i tried methods 1 & 2, both give a little different schema.

---

1. using django cli

mainly all you gotta do is run ./manage.py generateschema --file openapi-schema.yml source: https://www.django-rest-framework.org/api-guide/schemas/#generating-a-static-schema-with-the-generateschema-management-command

I am unsure right now, how this inbuilt command is different from spectacular

Anyways, this is the schema that it outputs: (for some reason github wont let me upload a yaml file smh; enjoy the screen bomb)

`generateschema-openapi.yml` ```yaml openapi: 3.0.2 info: title: '' version: '' paths: /authentication/me: get: operationId: listUsers description: '' parameters: [] responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/User' description: '' tags: - authentication /authentication/login: post: operationId: createLogin description: '' parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/Login' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Login' multipart/form-data: schema: $ref: '#/components/schemas/Login' responses: '201': content: application/json: schema: $ref: '#/components/schemas/Login' description: '' tags: - authentication /authentication/logout: post: operationId: createLogout description: '' parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/Logout' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Logout' multipart/form-data: schema: $ref: '#/components/schemas/Logout' responses: '201': content: application/json: schema: $ref: '#/components/schemas/Logout' description: '' tags: - authentication /authentication/token/refresh: post: operationId: createTokenRefresh description: 'Takes a refresh type JSON web token and returns an access type JSON web token if the refresh token is valid.' parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/TokenRefresh' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/TokenRefresh' multipart/form-data: schema: $ref: '#/components/schemas/TokenRefresh' responses: '201': content: application/json: schema: $ref: '#/components/schemas/TokenRefresh' description: '' tags: - authentication components: schemas: User: type: object properties: id: type: integer readOnly: true email: type: string format: email maxLength: 255 username: type: string maxLength: 255 created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true required: - email - username Login: type: object properties: email: type: string format: email maxLength: 255 minLength: 3 password: type: string writeOnly: true maxLength: 68 minLength: 6 tokens: type: string readOnly: true required: - email - password Logout: type: object properties: {} TokenRefresh: type: object properties: refresh: type: string access: type: string readOnly: true required: - refresh ```

---

2. from the /openapi endpoint

from the endpoint, this was the schema generated

`dynamic-schema-openapi.yml` ```yaml openapi: 3.0.2 info: title: urNode version: 1.0.0 description: Documentation paths: /authentication/login: post: operationId: createLogin description: '' parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/Login' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Login' multipart/form-data: schema: $ref: '#/components/schemas/Login' responses: '201': content: application/json: schema: $ref: '#/components/schemas/Login' description: '' tags: - authentication /authentication/token/refresh: post: operationId: createTokenRefresh description: 'Takes a refresh type JSON web token and returns an access type JSON web token if the refresh token is valid.' parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/TokenRefresh' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/TokenRefresh' multipart/form-data: schema: $ref: '#/components/schemas/TokenRefresh' responses: '201': content: application/json: schema: $ref: '#/components/schemas/TokenRefresh' description: '' tags: - authentication components: schemas: Login: type: object properties: email: type: string format: email maxLength: 255 minLength: 3 password: type: string writeOnly: true maxLength: 68 minLength: 6 tokens: type: string readOnly: true required: - email - password TokenRefresh: type: object properties: refresh: type: string access: type: string readOnly: true required: - refresh ```

---

3. Spectacular notes:

As for using spectacular, that requires you to configure some config files in django (see here)

---

It would be really helpful for me if you can diffcheck both the schemas and tell which one is the more appropriate one, since one difference b/w both that stumped me was that the cli generated one contained the schema for /authentication/logout but when getting it from /openapi that part was missing.

[0x0elliot]

the former one!

[0x0elliot]

godspeed for #4