diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a179851 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +# Dir for bundles +dist +node_modules diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..d41b8bd --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2016 Ivan Goncharov + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index c5a7d9c..297e101 100644 --- a/README.md +++ b/README.md @@ -6,76 +6,76 @@ O projeto de NFT da comunidade Python Floripa visa desenvolver uma plataforma co ## Objetivos Principais -1. **Capacitação dos membros:** Criar oportunidades para que desenvolvedores da comunidade Python Floripa aprendam e implementem soluções blockchain. - -2. **Conteúdo de referência:** Produzir documentação e conteúdo que sirvam como referência para a comunidade em geral. - -3. **Plataforma de NFTs:** Desenvolver uma plataforma de ponta a ponta que integre um provedor de blockchain, como Ethereum, para permitir o cadastro, resgate e validação de NFTs. - -4. **Aplicações práticas:** Criar soluções práticas como: -* Certificados de participação em eventos, gerados automaticamente com base no check-in dos participantes. +1. **Capacitação dos membros:** Criar oportunidades para que desenvolvedores da comunidade Python Floripa aprendam e implementem soluções blockchain. + +2. **Conteúdo de referência:** Produzir documentação e conteúdo que sirvam como referência para a comunidade em geral. + +3. **Plataforma de NFTs:** Desenvolver uma plataforma de ponta a ponta que integre um provedor de blockchain, como Ethereum, para permitir o cadastro, resgate e validação de NFTs. + +4. **Aplicações práticas:** Criar soluções práticas como: +* Certificados de participação em eventos, gerados automaticamente com base no check-in dos participantes. * NFTs de cards para eventos e palestras, permitindo que participantes resgatem NFTs personalizados com base na sua presença. -**Certificado de Participação via NFT**: Cada participante que fizer check-in em um evento da Python Floripa poderá resgatar um NFT como certificado digital, garantindo a autenticidade de sua participação. -**Cards NFT para eventos e palestras**: Cada evento ou atividade da comunidade terá um card digital vinculado a um NFT, que poderá ser resgatado por participantes após validação do check-in. +**Certificado de Participação via NFT**: Cada participante que fizer check-in em um evento da Python Floripa poderá resgatar um NFT como certificado digital, garantindo a autenticidade de sua participação. +**Cards NFT para eventos e palestras**: Cada evento ou atividade da comunidade terá um card digital vinculado a um NFT, que poderá ser resgatado por participantes após validação do check-in. **Popularização da Blockchain**: Facilitar a compreensão e utilização da tecnologia blockchain por parte da comunidade e da sociedade em geral, aproximando os desenvolvedores da prática e fomentando a difusão desse conhecimento. ## Objetivos Específicos -1. **Ferramenta para várias comunidades:** A plataforma será disponibilizada publicamente e poderá ser utilizada por outras comunidades interessadas, mediante a compra de créditos para cobrir os custos de infraestrutura, como o pagamento ao provedor de blockchain. - -2. **Desenvolvimento colaborativo:** Todo o código-fonte será desenvolvido de forma colaborativa e aberto no GitHub da comunidade Python Floripa. - -3. **Construção de autoridade:** Participantes diretos do desenvolvimento poderão adicionar suas contribuições ao projeto em seus portfólios, destacando sua participação para fins de progressão profissional. - +1. **Ferramenta para várias comunidades:** A plataforma será disponibilizada publicamente e poderá ser utilizada por outras comunidades interessadas, mediante a compra de créditos para cobrir os custos de infraestrutura, como o pagamento ao provedor de blockchain. + +2. **Desenvolvimento colaborativo:** Todo o código-fonte será desenvolvido de forma colaborativa e aberto no GitHub da comunidade Python Floripa. + +3. **Construção de autoridade:** Participantes diretos do desenvolvimento poderão adicionar suas contribuições ao projeto em seus portfólios, destacando sua participação para fins de progressão profissional. + 4. **Documentação e Live Weeklys:** O desenvolvimento será documentado e acompanhado por transmissões semanais ao vivo entre os membros do squad de desenvolvimento, para discutir a evolução, distribuir demandas e relatar a evolução do projeto. Essas lives serão disponibilizadas no YouTube da comunidade. ## Especificação Técnica ### Estrutura da Plataforma -1. **Backend:** A plataforma será desenvolvida em Python, com integração a um provedor de blockchain (e.g., Ethereum). Será responsável por: -* Gerenciar o cadastro dos eventos e usuários. -* Verificar o check-in dos participantes nos eventos. -* Emitir e associar NFTs aos participantes. - -2. **Frontend:** Interface simples e amigável para permitir que os usuários façam o resgate dos NFTs gerados. O design será responsivo, permitindo fácil acesso em diferentes dispositivos. - -3. **Integração com Blockchain:** A plataforma terá integração com o blockchain escolhido (e.g., Ethereum) para a criação e validação dos NFTs. Utilizaremos smart contracts para garantir a segurança e transparência das transações. - +1. **Backend:** A plataforma será desenvolvida em Python, com integração a um provedor de blockchain (e.g., Ethereum). Será responsável por: +* Gerenciar o cadastro dos eventos e usuários. +* Verificar o check-in dos participantes nos eventos. +* Emitir e associar NFTs aos participantes. + +2. **Frontend:** Interface simples e amigável para permitir que os usuários façam o resgate dos NFTs gerados. O design será responsivo, permitindo fácil acesso em diferentes dispositivos. + +3. **Integração com Blockchain:** A plataforma terá integração com o blockchain escolhido (e.g., Ethereum) para a criação e validação dos NFTs. Utilizaremos smart contracts para garantir a segurança e transparência das transações. + 4. **Banco de Dados:** Sistema de banco de dados para armazenar os eventos, usuários, e NFTs gerados, garantindo a rastreabilidade e segurança dos dados. ### Cronograma e Marcos do Projeto -1. **Planejamento e Design** (prazo?): -* Definir os requisitos detalhados. -* Estruturar o backend e a integração com o blockchain. -* Prototipar a interface. - -2. **Desenvolvimento** (prazo?): -* Implementação do backend e frontend. -* Configuração da integração com o blockchain. -* Testes iniciais com a comunidade. -* Publicar documentação no GitHub. - -3. **Lançamento Beta** (prazo?): -* Disponibilizar a versão beta da plataforma para testes com os membros da comunidade. - -4. **Ajustes e Lançamento** (prazo?): -* Correção e ajustes de código. -* Realizar lives de apresentação da solução. -* Recrutar embaixadores para divulgar o projeto em eventos diversos. +1. **Planejamento e Design** (prazo?): +* Definir os requisitos detalhados. +* Estruturar o backend e a integração com o blockchain. +* Prototipar a interface. + +2. **Desenvolvimento** (prazo?): +* Implementação do backend e frontend. +* Configuração da integração com o blockchain. +* Testes iniciais com a comunidade. +* Publicar documentação no GitHub. + +3. **Lançamento Beta** (prazo?): +* Disponibilizar a versão beta da plataforma para testes com os membros da comunidade. + +4. **Ajustes e Lançamento** (prazo?): +* Correção e ajustes de código. +* Realizar lives de apresentação da solução. +* Recrutar embaixadores para divulgar o projeto em eventos diversos. * Divulgação nas redes sociais e eventos da comunidade. ## Referencias **Benchmark** -[https://poap.xyz/](https://poap.xyz/) +[https://poap.xyz/](https://poap.xyz/) + +**Ferramentas para Desenhar Arquitetura** +draw.io +[https://structurizr.com](https://structurizr.com/) -**Ferramentas para Desenhar Arquitetura** -draw.io -[https://structurizr.com](https://structurizr.com/) - ## Comentários e Devaneios ## Requisitos funcionais @@ -99,6 +99,4 @@ draw.io - certifica que participou das atividades do Eventos ## Requisitos não-funcionais -- deploy na AWS (?) - - +- deploy na AWS (?) \ No newline at end of file diff --git a/docs/.redocly.yaml b/docs/.redocly.yaml new file mode 100644 index 0000000..ce708cf --- /dev/null +++ b/docs/.redocly.yaml @@ -0,0 +1,26 @@ +# See https://redoc.ly/docs/cli/configuration/ for more information. +extends: + - recommended +apis: + core@v1: + root: ./openapi/openapi.yaml + rules: + no-ambiguous-paths: error + theme: + openapi: + hideLogo: false + decorators: + remove-x-internal: on +rules: + no-unused-components: error + operation-singular-tag: warn + boolean-parameter-prefixes: + severity: error + prefixes: ["can", "is", "has"] +theme: + openapi: + schemaExpansionLevel: 2 + generateCodeSamples: + languages: + - lang: curl + - lang: Python diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..edbfbc1 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,32 @@ + + + + + + + My New API + + + +
+ + + + \ No newline at end of file diff --git a/docs/openapi.yaml b/docs/openapi.yaml new file mode 100644 index 0000000..3a2c3df --- /dev/null +++ b/docs/openapi.yaml @@ -0,0 +1,174 @@ +openapi: 3.0.2 +info: + version: 1.0.0 + title: NFT Python Floripa + termsOfService: https://example.com/terms/ + contact: + email: contact@example.com + url: http://example.com/contact + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0.html + x-logo: + url: https://redocly.github.io/openapi-template/logo.png + description: | + NFT API Documentation. +servers: + - url: https://pop.cloudman.pro +tags: + - name: Cadastro + description: Example echo operations + - name: Certificado + description: Operations about user +externalDocs: + description: Find out how to create a GitHub repo for your OpenAPI definition. + url: https://github.com/Rebilly/generator-openapi-repo +paths: + /pop/Auth-pop: + post: + operationId: create_user + tags: + - Cadastro + summary: Create a new user + deprecated: false + description: Create a new user + requestBody: + description: User object that needs to be added to the system + content: + application/json: + schema: + $ref: '#/components/schemas/CreateUser' + required: true + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/User' + application/xml: + schema: + $ref: '#/components/schemas/User' + '400': + description: Invalid user supplied + '409': + description: User already exists + /pop/OrgAdmin-pop: + post: + operationId: create_certificate + tags: + - Certificado + summary: Create a new certificate + deprecated: false + description: Create a new certificate + requestBody: + description: Certificate object that needs to be added to the system + content: + application/json: + schema: + $ref: '#/components/schemas/CreateCertificate' + required: true + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/CertificateCreated' + application/xml: + schema: + $ref: '#/components/schemas/CertificateCreated' + '409': + description: Item não encontrado na DynamoDB +components: + securitySchemes: + main_auth: + type: oauth2 + flows: + implicit: + authorizationUrl: http://example.com/api/oauth/dialog + scopes: + read:users: read users info + write:users: modify or remove users + api_key: + type: apiKey + in: header + name: api_key + basic_auth: + type: http + scheme: basic + schemas: + User: + properties: + name: + description: User Name + type: string + minLength: 4 + example: John Smith + Email: + properties: + email: + description: User email address + type: string + format: test + example: john.smith@example.com + CreateUser: + type: object + title: Create User + description: Create a new user + required: + - name + - email + - action + - otp + allOf: + - $ref: '#/components/schemas/User' + - $ref: '#/components/schemas/Email' + properties: + action: + type: string + enum: + - verify + - register + - process-link + format: test + description: Action to be performed + otp: + type: string + example: '123456' + format: test + description: OTP code + Certificate: + properties: + orgName: + description: Organization name + type: string + format: test + example: Example Inc. + eventName: + description: Event name + type: string + format: test + example: Example Event + CreateCertificate: + type: object + title: Create User + description: Create a new user + required: + - orgName + - eventName + allOf: + - $ref: '#/components/schemas/Certificate' + properties: + action: + type: string + enum: + - StartCreateCerts + format: text + description: Action to be performed + CertificateCreated: + properties: + attendeeCounter: + description: Number of attendees + type: integer + format: int32 diff --git a/docs/openapi/README.md b/docs/openapi/README.md new file mode 100644 index 0000000..ae48cf0 --- /dev/null +++ b/docs/openapi/README.md @@ -0,0 +1,13 @@ +## The `openapi` folder + +This folder contains your entrypoint `openapi.yaml`. + +That file contains references to the entire API definition. + +Here are some sections to pay attention to: + +* Top-level **description**: this accepts markdown, and Redoc and Redocly API Reference will render it at the top of the docs. Consider maintaining your markdown in a separate file and [embedding it](https://redoc.ly/docs/api-reference-docs/embedded-markdown/). Note to Redoc community edition users, the special tags are only available to the Redocly API Reference users, but you can still embed markdown. +* Security schemes: you will define the scheme(s) your API uses for security (eg OAuth2, API Key, etc...). The security schemes are used by the Redocly API Reference "Try It" API console feature. +* [Paths](paths/README.md): this defines each endpoint. A path can have one operation per http method. +* Tags: it's a good idea to organize each operation. Each tag can have a description. The description is used as a section description within the reference docs. +* Servers: a list of your servers, each with a URL. diff --git a/docs/openapi/code_samples/C#/echo/post.cs b/docs/openapi/code_samples/C#/echo/post.cs new file mode 100644 index 0000000..a91d094 --- /dev/null +++ b/docs/openapi/code_samples/C#/echo/post.cs @@ -0,0 +1,12 @@ +API.v1.Echo echo = new API.v1.Echo(); +echo.message = "Hello World!"); +EchoResponse response = echo.post(); +if (response.statusCode == HttpStatusCode.Created) +{ + // Success +} +else +{ + // Something wrong -- check response for errors + Console.WriteLine(response.getRawResponse()); +} diff --git a/docs/openapi/code_samples/PHP/echo/post.php b/docs/openapi/code_samples/PHP/echo/post.php new file mode 100644 index 0000000..72da145 --- /dev/null +++ b/docs/openapi/code_samples/PHP/echo/post.php @@ -0,0 +1,7 @@ +$form = new \API\Entities\Echo(); +$form->setMessage("Hello World!"); +try { + $pet = $client->echo()->post($form); +} catch (UnprocessableEntityException $e) { + var_dump($e->getErrors()); +} diff --git a/docs/openapi/code_samples/README.md b/docs/openapi/code_samples/README.md new file mode 100644 index 0000000..2e57b12 --- /dev/null +++ b/docs/openapi/code_samples/README.md @@ -0,0 +1,11 @@ +Code samples +===== + +This is our recommended convention for organizing `code_samples`: + +[x-code-samples](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-code-samples) +Path `//.` where: + * `` - name of the language from [this](https://github.com/github/linguist/blob/master/lib/linguist/popular.yml) list. + * `` - path of the target method, where all `/` are replaced with `@`. + * `` - verb of target method. + * `` - ignored. diff --git a/docs/openapi/components/README.md b/docs/openapi/components/README.md new file mode 100644 index 0000000..26eaeb5 --- /dev/null +++ b/docs/openapi/components/README.md @@ -0,0 +1,14 @@ +Reusable components +=========== + +* You can create the following folders here: + - `schemas` - reusable [Schema Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaObject) + - `responses` - reusable [Response Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responseObject) + - `parameters` - reusable [Parameter Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject) + - `examples` - reusable [Example Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#exampleObject) + - `headers` - reusable [Header Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#headerObject) + - `requestBodies` - reusable [Request Body Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#requestBodyObject) + - `links` - reusable [Link Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#linkObject) + - `callbacks` - reusable [Callback Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#callbackObject) + - `securitySchemes` - reusable [Security Scheme Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#securitySchemeObject) +* Filename of files inside the folders represent component name, e.g. `Customer.yaml` diff --git a/docs/openapi/components/headers/ExpiresAfter.yaml b/docs/openapi/components/headers/ExpiresAfter.yaml new file mode 100644 index 0000000..0cbe9a5 --- /dev/null +++ b/docs/openapi/components/headers/ExpiresAfter.yaml @@ -0,0 +1,4 @@ +description: date in UTC when token expires +schema: + type: string + format: date-time diff --git a/docs/openapi/components/schemas/Certificate.yaml b/docs/openapi/components/schemas/Certificate.yaml new file mode 100644 index 0000000..184a00f --- /dev/null +++ b/docs/openapi/components/schemas/Certificate.yaml @@ -0,0 +1,11 @@ +properties: + orgName: + description: Organization name + type: string + format: test + example: "Example Inc." + eventName: + description: Event name + type: string + format: test + example: "Example Event" diff --git a/docs/openapi/components/schemas/Email.yaml b/docs/openapi/components/schemas/Email.yaml new file mode 100644 index 0000000..121bd6b --- /dev/null +++ b/docs/openapi/components/schemas/Email.yaml @@ -0,0 +1,6 @@ +properties: + email: + description: User email address + type: string + format: test + example: john.smith@example.com diff --git a/docs/openapi/components/schemas/User.yaml b/docs/openapi/components/schemas/User.yaml new file mode 100644 index 0000000..7d4e497 --- /dev/null +++ b/docs/openapi/components/schemas/User.yaml @@ -0,0 +1,6 @@ +properties: + name: + description: User Name + type: string + minLength: 4 + example: John Smith diff --git a/docs/openapi/components/securitySchemes/api_key.yaml b/docs/openapi/components/securitySchemes/api_key.yaml new file mode 100644 index 0000000..359e56e --- /dev/null +++ b/docs/openapi/components/securitySchemes/api_key.yaml @@ -0,0 +1,3 @@ +type: apiKey +in: header +name: api_key diff --git a/docs/openapi/components/securitySchemes/basic_auth.yaml b/docs/openapi/components/securitySchemes/basic_auth.yaml new file mode 100644 index 0000000..d016600 --- /dev/null +++ b/docs/openapi/components/securitySchemes/basic_auth.yaml @@ -0,0 +1,2 @@ +type: http +scheme: basic diff --git a/docs/openapi/components/securitySchemes/main_auth.yaml b/docs/openapi/components/securitySchemes/main_auth.yaml new file mode 100644 index 0000000..a8ba56c --- /dev/null +++ b/docs/openapi/components/securitySchemes/main_auth.yaml @@ -0,0 +1,7 @@ +type: oauth2 +flows: + implicit: + authorizationUrl: 'http://example.com/api/oauth/dialog' + scopes: + 'read:users': read users info + 'write:users': modify or remove users diff --git a/docs/openapi/openapi.yaml b/docs/openapi/openapi.yaml new file mode 100644 index 0000000..cd659bc --- /dev/null +++ b/docs/openapi/openapi.yaml @@ -0,0 +1,99 @@ +openapi: 3.0.2 +info: + version: 1.0.0 + title: NFT Python Floripa + termsOfService: "https://example.com/terms/" + contact: + email: contact@example.com + url: "http://example.com/contact" + license: + name: Apache 2.0 + url: "http://www.apache.org/licenses/LICENSE-2.0.html" + x-logo: + url: "https://redocly.github.io/openapi-template/logo.png" + description: > + NFT API Documentation. +externalDocs: + description: Find out how to create a GitHub repo for your OpenAPI definition. + url: "https://github.com/Rebilly/generator-openapi-repo" +tags: + - name: Cadastro + description: Example echo operations + - name: Certificado + description: Operations about user +servers: + - url: "https://pop.cloudman.pro" +paths: + /pop/Auth-pop: + post: + operationId: create_user + tags: + - Cadastro + summary: Create a new user + deprecated: false + description: Create a new user + requestBody: + description: User object that needs to be added to the system + content: + application/json: + schema: + $ref: ./requests/CreateUser.yaml + required: true + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: ./components/schemas/User.yaml + application/xml: + schema: + $ref: ./components/schemas/User.yaml + "400": + description: Invalid user supplied + "409": + description: User already exists + /pop/OrgAdmin-pop: + post: + operationId: create_certificate + tags: + - Certificado + summary: Create a new certificate + deprecated: false + description: Create a new certificate + requestBody: + description: Certificate object that needs to be added to the system + content: + application/json: + schema: + $ref: ./requests/CreateCertificate.yaml + required: true + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: ./responses/CertificateCreated.yaml + application/xml: + schema: + $ref: ./responses/CertificateCreated.yaml + "409": + description: Item não encontrado na DynamoDB +components: + securitySchemes: + main_auth: + type: oauth2 + flows: + implicit: + authorizationUrl: "http://example.com/api/oauth/dialog" + scopes: + "read:users": read users info + "write:users": modify or remove users + api_key: + type: apiKey + in: header + name: api_key + basic_auth: + type: http + scheme: basic diff --git a/docs/openapi/paths/README.md b/docs/openapi/paths/README.md new file mode 100644 index 0000000..0449659 --- /dev/null +++ b/docs/openapi/paths/README.md @@ -0,0 +1,105 @@ +Paths +===== + +Organize your path definitions within this folder. You will reference your paths from your main `openapi.yaml` entrypoint file. + +It may help you to adopt some conventions: + +* path separator token (e.g. `@`) or subfolders +* path parameter (e.g. `{example}`) +* file-per-path or file-per-operation + +There are different benefits and drawbacks to each decision. + +You can adopt any organization you wish. We have some tips for organizing paths based on common practices. + +## Each path in a separate file + +Use a predefined "path separator" and keep all of your path files in the top level of the `paths` folder. + +``` +# todo: insert tree view of paths folder +``` + +Redocly recommends using the `@` character for this case. + +In addition, Redocly recommends placing path parameters within `{}` curly braces if you adopt this style. + +#### Motivations + +* Quickly see a list of all paths. Many people think in terms of the "number" of "endpoints" (paths), and not the "number" of "operations" (paths * http methods). + +* Only the "file-per-path" option is semantically correct with the OpenAPI Specification 3.0.2. However, Redocly's openapi-cli will build valid bundles for any of the other options too. + + +#### Drawbacks + +* This may require multiple definitions per http method within a single file. +* It requires settling on a path separator (that is allowed to be used in filenames) and sticking to that convention. + +## Each operation in a separate file + +You may also place each operation in a separate file. + +In this case, if you want all paths at the top-level, you can concatenate the http method to the path name. Similar to the above option, you can + +### Files at top-level of `paths` + +You may name your files with some concatenation for the http method. For example, following a convention such as: `-.yaml`. + +#### Motivations + +* Quickly see all operations without needing to navigate subfolders. + +#### Drawbacks + +* Adopting an unusual path separator convention, instead of using subfolders. + +### Use subfolders to mirror API path structure + +Example: +``` +GET /customers + +/paths/customers/get.yaml +``` + +In this case, the path id defined within subfolders which mirror the API URL structure. + +Example with path parameter: +``` +GET /customers/{id} + +/paths/customers/{id}/get.yaml +``` + +#### Motivations + +It matches the URL structure. + +It is pretty easy to reference: + +```yaml +paths: + '/customers/{id}': + get: + $ref: ./paths/customers/{id}/get.yaml + put: + $ref: ./paths/customers/{id}/put.yaml +``` + +#### Drawbacks + +If you have a lot of nested folders, it may be confusing to reference your schemas. + +Example +``` +file: /paths/customers/{id}/timeline/{messageId}/get.yaml + +# excerpt of file + headers: + Rate-Limit-Remaining: + $ref: ../../../../../components/headers/Rate-Limit-Remaining.yaml + +``` +Notice the `../../../../../` in the ref which requires some attention to formulate correctly. While openapi-cli has a linter which suggests possible refs when there is a mistake, this is still a net drawback for APIs with deep paths. diff --git a/docs/openapi/paths/echo.yaml b/docs/openapi/paths/echo.yaml new file mode 100644 index 0000000..24cfed1 --- /dev/null +++ b/docs/openapi/paths/echo.yaml @@ -0,0 +1,45 @@ +post: + tags: + - Echo + summary: Echo test + description: Receive the exact message you've sent + operationId: echo + security: + - api_key: [] + - basic_auth: [] + responses: + '200': + description: OK + headers: + X-Rate-Limit: + description: calls per hour allowed by the user + schema: + type: integer + format: int32 + X-Expires-After: + $ref: ../components/headers/ExpiresAfter.yaml + content: + application/json: + schema: + type: string + examples: + response: + value: Hello world! + application/xml: + schema: + type: string + text/csv: + schema: + type: string + requestBody: + content: + application/json: + schema: + type: string + example: Hello world! + application/xml: + schema: + type: string + example: Hello world! + description: Echo payload + required: true diff --git a/docs/openapi/paths/users@{username}.yaml b/docs/openapi/paths/users@{username}.yaml new file mode 100644 index 0000000..8710003 --- /dev/null +++ b/docs/openapi/paths/users@{username}.yaml @@ -0,0 +1,77 @@ +parameters: + - name: pretty_print + in: query + description: Pretty print response + schema: + type: boolean +get: + tags: + - User + summary: Get user by user name + description: | + Some description of the operation. + You can use `markdown` here. + operationId: getUserByName + parameters: + - name: username + in: path + description: The name that needs to be fetched + required: true + schema: + type: string + - name: with_email + in: query + description: Filter users without email + schema: + type: boolean + security: + - main_auth: + - 'read:users' + - api_key: [] + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: ../components/schemas/User.yaml + example: + username: user1 + email: user@example.com + '403': + description: Forbidden + '404': + description: User not found +put: + tags: + - User + summary: Updated user + description: This can only be done by the logged in user. + operationId: updateUser + parameters: + - name: username + in: path + description: The name that needs to be updated + required: true + schema: + type: string + security: + - main_auth: + - 'write:users' + responses: + '200': + description: OK + '400': + description: Invalid user supplied + '404': + description: User not found + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/User.yaml + application/xml: + schema: + $ref: ../components/schemas/User.yaml + description: Updated user object + required: true diff --git a/docs/openapi/requests/CreateCertificate.yaml b/docs/openapi/requests/CreateCertificate.yaml new file mode 100644 index 0000000..dca0021 --- /dev/null +++ b/docs/openapi/requests/CreateCertificate.yaml @@ -0,0 +1,15 @@ +type: object +title: Create User +description: Create a new user +required: + - orgName + - eventName +allOf: + - $ref: ../components/schemas/Certificate.yaml +properties: + action: + type: string + enum: + - StartCreateCerts + format: text + description: Action to be performed diff --git a/docs/openapi/requests/CreateUser.yaml b/docs/openapi/requests/CreateUser.yaml new file mode 100644 index 0000000..1601ecf --- /dev/null +++ b/docs/openapi/requests/CreateUser.yaml @@ -0,0 +1,25 @@ +type: object +title: Create User +description: Create a new user +required: + - name + - email + - action + - otp +allOf: + - $ref: ../components/schemas/User.yaml + - $ref: ../components/schemas/Email.yaml +properties: + action: + type: string + enum: + - verify + - register + - process-link + format: test + description: Action to be performed + otp: + type: string + example: "123456" + format: test + description: OTP code diff --git a/docs/openapi/responses/CertificateCreated.yaml b/docs/openapi/responses/CertificateCreated.yaml new file mode 100644 index 0000000..a00d6b9 --- /dev/null +++ b/docs/openapi/responses/CertificateCreated.yaml @@ -0,0 +1,5 @@ +properties: + attendeeCounter: + description: Number of attendees + type: integer + format: int32