-
-
Notifications
You must be signed in to change notification settings - Fork 87
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #366 from vishalkhoje/feature/add-new-page-integra…
…tion feat: New integration post page added
- Loading branch information
Showing
3 changed files
with
264 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,95 @@ | ||
| --- | ||
| import Header from "../components/header.astro"; | ||
| import Footer from "../components/footer.astro"; | ||
| // Use Astro.glob() to fetch all posts, and then sort them by date. | ||
| const posts = (await Astro.glob("./integration/*.{md,mdx}")).sort( | ||
| (a, b) => | ||
| new Date(b.frontmatter.pubDate).valueOf() - | ||
| new Date(a.frontmatter.pubDate).valueOf() | ||
| ); | ||
| --- | ||
|
|
||
| <!doctype html> | ||
| <html lang="en"> | ||
| <head> | ||
| <style> | ||
| ul { | ||
| list-style-type: none; | ||
| padding: unset; | ||
| } | ||
| ul li { | ||
| display: flex; | ||
| } | ||
| ul li time { | ||
| flex: 0 0 130px; | ||
| font-style: italic; | ||
| color: #595959; | ||
| } | ||
| ul li a:visited { | ||
| color: #8e32dc; | ||
| } | ||
| </style> | ||
| </head> | ||
| <body class="bg-gray-800 overflow-x-hidden"> | ||
| <Header /> | ||
| <main> | ||
| <div class="relative px-4 pt-8 pb-20 sm:px-6 lg:px-8 lg:pt-16 lg:pb-28"> | ||
| <div class="absolute inset-0"> | ||
| <div | ||
| class="h-1/3 bg-gradient-to-b from-indigo-700 to-gray-800 sm:h-2/3" | ||
| > | ||
| </div> | ||
| </div> | ||
| <div class="relative mx-auto max-w-7xl"> | ||
| <div class="text-center"> | ||
| <h2 | ||
| class="text-4xl font-bold tracking-tight text-pink-400 sm:text-4xl" | ||
| > | ||
| The Mocked Integration | ||
| </h2> | ||
| <p class="mx-auto mt-3 max-w-3xl text-xl text-gray-200 sm:mt-4"> | ||
| Updates from the world of mocked-api. | ||
| </p> | ||
| </div> | ||
| <div | ||
| class="mx-auto mt-12 grid max-w-lg gap-5 lg:max-w-none lg:grid-cols-3" | ||
| > | ||
| {posts.map((post) => ( | ||
| <div class="flex flex-col overflow-hidden rounded-lg shadow-lg bg-gradient-to-b from-indigo-700 to-purple-800 p-4"> | ||
| <div class="flex-shrink-0"> | ||
| <img class="mb-4" src={post.frontmatter.heroImage} alt=""> | ||
| </div> | ||
| <div class="flex flex-1 flex-col justify-between bg-white p-6 border-r-pink-300 border-4"> | ||
| <div class="flex-1"> | ||
| <p class="text-sm font-medium text-indigo-600"> | ||
| {post.frontmatter.category} | ||
| </p> | ||
| <div class="mt-2 block"> | ||
| <p class="text-xl font-semibold text-gray-900">{post.frontmatter.title}</p> | ||
| <p class="mt-3 text-base text-gray-500">{post.frontmatter.summary}</p> | ||
| </div> | ||
| </div> | ||
| <div class="mt-6 flex items-center"> | ||
| <p class="text-sm font-medium text-gray-900"> | ||
| <a href="#" class="hover:underline">{post.frontmatter.author}</a> | ||
| </p> | ||
| <div class="flex space-x-1 text-sm text-gray-500 ml-2"> | ||
| {post.frontmatter.pubDate} | ||
| </div> | ||
| </div> | ||
| <a href={post.url} class="m-auto"> | ||
| <button class="bg-blue-500 w-60 m-auto mt-4 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"> | ||
| Read more | ||
| </button> | ||
| </a> | ||
| </div> | ||
| </div> | ||
| ))} | ||
| </div> | ||
| </div> | ||
| </div> | ||
| </main> | ||
| <Footer /> | ||
| </body> | ||
| </html> |
168 changes: 168 additions & 0 deletions
168
marketing-site/src/pages/integration/add-api-endpoint.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,168 @@ | ||
| --- | ||
| layout: ../../layouts/BlogPost.astro | ||
| title: "Add an API endpoint" | ||
| pubDate: "01th October 2023" | ||
| heroImage: "/Hfest-Logo-2-Color-Manga.png" | ||
| category: "news" | ||
| summary: "We are suppy happy to be apart of hacktoberfest this year..." | ||
| author: "Aaron Rackley" | ||
| --- | ||
|
|
||
| Add an API endpoint | ||
| =================== | ||
|
|
||
| This example will use `users` as a new TAG for OpenAPI, meaning we will have dedicated endpoints to get some mocked users or create new ones. | ||
|
|
||
| How to add an endpoint | ||
| ---------------------- | ||
|
|
||
| Endpoints should be created in a `<TOPIC>-routes.ts` file under `./modules/<TOPIC>/api` folder. | ||
| We assume `<TOPIC>` as a new TAG on OpenAPI, meaning a different category with dedicated endpoints like `address`, `countries`, `currency`, and son on... We will use `users` topic in our examples. | ||
|
|
||
| Example on how to create and endpoint for a new topic: | ||
|
|
||
| - 1 - Create a new folder with the topic name, under `./modules` folder, like `./modules/users` | ||
| - 2 - Create a new file with mocked data, under `./modules/users/data`, like `./modules/users/data/users.ts`. | ||
| - 3 - Create an `api` folder to store the `routes` file, like `./modules/users/api/users-routes.ts` | ||
| - 4 - Create different endpoints for users. Example: | ||
|
|
||
| ```javascript | ||
| import usersList from "../data/users"; | ||
|
|
||
| module.exports = function (app: core.Express) { | ||
| app.get("/users", (req: Request, res: Response) => { | ||
| res.json({ | ||
| users: usersList, | ||
| }); | ||
| }); | ||
| }; | ||
| ``` | ||
|
|
||
| Note: This endpoint will fetch all mocked users stored in `./modules/users/data/users.ts` | ||
|
|
||
| How to write tests | ||
| ---------------------- | ||
|
|
||
| For each module you create you will also need to create a tests folder, Inside this folder there should be a `api` and `utils` | ||
| (if you create any utils) folder. | ||
|
|
||
| The utils tests are fairly simple jests tests, the `api` routes tests are slightly different where you will need to add | ||
|
|
||
| ```javascript | ||
| import request from "supertest"; | ||
| import app from "path/to/app"; | ||
| ``` | ||
|
|
||
| to your tests and make a request in your test instead of calling a normal function. | ||
|
|
||
| How to run tests | ||
| ---------------------- | ||
|
|
||
| run `npm test` | ||
| run `npm run test:watch` to run the tests in watch mode. | ||
|
|
||
| How to add OpenAPI comments | ||
| ---------------------- | ||
|
|
||
| For each endpoint you should do an OpenAPI comment, this way, you will make sure your endpoint will be reflected in swagger, as well as the response schema and type are correct. | ||
| To describe describe an endpoint as an OpenAPI comment, you should use the yaml structure like this: | ||
|
|
||
| - 1 - Define the path | ||
| - 2 - Define the http method referent to that path | ||
| - 3 - Define the tag in order to group all endpoints referent to the same TAG (in this case, all `users` endpoints will be grouped under the tag `Users`) | ||
| - 4 - Define a brief summary of you endpoint | ||
| - 5 - Define the response types for the endpoint (200 - OK ; 404 - Not found, etc...) | ||
| - 6 - Define the schema of the response | ||
|
|
||
| Note: You can define the properties of each schema or reuse a schema that already exists | ||
|
|
||
| Each OpenAPI comment should start with `@openapi` in order to be read by swagger and reflected on it. | ||
|
|
||
| Example: | ||
|
|
||
| ```javascript | ||
| /** | ||
| * @openapi | ||
| * '/users': | ||
| * get: | ||
| * tags: | ||
| * - Users | ||
| * summary: Obtain a list of all users | ||
| * responses: | ||
| * '200': | ||
| * description: OK | ||
| * schema: | ||
| * type: array | ||
| * items: | ||
| * type: object | ||
| * properties: | ||
| * email: | ||
| * type: string | ||
| * example: example@example.com | ||
| * gender: | ||
| * type: string | ||
| * example: male | ||
| * username: | ||
| * type: string | ||
| * example: user00000 | ||
| * first_name: | ||
| * type: string | ||
| * example: John | ||
| * last_name: | ||
| * type: string | ||
| * example: Doe | ||
| * title: | ||
| * type: string | ||
| * example: mr | ||
| */ | ||
| ``` | ||
|
|
||
| This describe the get endpoint that we did [here](#how-to-add-an-endpoint). | ||
|
|
||
| After doing the OpenAPI comment: | ||
|
|
||
| ```javascript | ||
| import usersList from "../data/users"; | ||
|
|
||
| module.exports = function (app: core.Express) { | ||
| /** | ||
| * @openapi | ||
| * '/users': | ||
| * get: | ||
| * tags: | ||
| * - Users | ||
| * summary: Obtain a list of all users | ||
| * responses: | ||
| * '200': | ||
| * description: OK | ||
| * schema: | ||
| * type: array | ||
| * items: | ||
| * type: object | ||
| * properties: | ||
| * email: | ||
| * type: string | ||
| * example: example@example.com | ||
| * gender: | ||
| * type: string | ||
| * example: male | ||
| * username: | ||
| * type: string | ||
| * example: user00000 | ||
| * first_name: | ||
| * type: string | ||
| * example: John | ||
| * last_name: | ||
| * type: string | ||
| * example: Doe | ||
| * title: | ||
| * type: string | ||
| * example: mr | ||
| */ | ||
| app.get("/users", (req: Request, res: Response) => { | ||
| res.json({ | ||
| users: usersList, | ||
| }); | ||
| }); | ||
| }; | ||
| ``` |