diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml new file mode 100644 index 0000000..3571619 --- /dev/null +++ b/.github/workflows/publish-docs.yml @@ -0,0 +1,42 @@ +on: + push: + tags: + - "*" + +permissions: + actions: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + publish-docs: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Dotnet Setup + uses: actions/setup-dotnet@v3 + with: + dotnet-version: 8.x + + - run: dotnet tool update -g docfx + - run: docfx docs/docfx.json + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: 'docs/_site' + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 \ No newline at end of file diff --git a/.gitignore b/.gitignore index 2c3317d..a116414 100644 --- a/.gitignore +++ b/.gitignore @@ -555,3 +555,6 @@ coverage.json coverage.cobertura.xml # End of https://www.gitignore.io/api/aspnetcore,visualstudio,visualstudiocode,openframeworks+visualstudio + +docs/_site +docs/api \ No newline at end of file diff --git a/CoreZipCode/Interfaces/PostCodeBaseService.cs b/CoreZipCode/Interfaces/PostCodeBaseService.cs index 844a246..ca5af9c 100644 --- a/CoreZipCode/Interfaces/PostCodeBaseService.cs +++ b/CoreZipCode/Interfaces/PostCodeBaseService.cs @@ -4,19 +4,16 @@ namespace CoreZipCode.Interfaces { - /// /// /// Postcode base service abstract class. /// public abstract class PostcodeBaseService : ApiHandler { - /// /// /// postalcode base service protected constructor. /// protected PostcodeBaseService() { } - /// /// /// postalcode base service protected constructor. /// diff --git a/CoreZipCode/Interfaces/ZipCodeBaseService.cs b/CoreZipCode/Interfaces/ZipCodeBaseService.cs index 94cad39..7624f49 100644 --- a/CoreZipCode/Interfaces/ZipCodeBaseService.cs +++ b/CoreZipCode/Interfaces/ZipCodeBaseService.cs @@ -5,19 +5,16 @@ namespace CoreZipCode.Interfaces { - /// /// /// Zip code base service abstract class /// public abstract class ZipCodeBaseService : ApiHandler { - /// /// /// Zip Code Base Service protected constructor. /// protected ZipCodeBaseService() { } - /// /// /// Zip Code Base Service protected constructor. /// diff --git a/CoreZipCode/Services/Postcode/PostalpincodeInApi/PostalpincodeIn.cs b/CoreZipCode/Services/Postcode/PostalpincodeInApi/PostalpincodeIn.cs index 58153a9..5796c79 100644 --- a/CoreZipCode/Services/Postcode/PostalpincodeInApi/PostalpincodeIn.cs +++ b/CoreZipCode/Services/Postcode/PostalpincodeInApi/PostalpincodeIn.cs @@ -3,6 +3,13 @@ namespace CoreZipCode.Services.Postcode.PostalpincodeInApi { + /// + /// Provides access to the Postalpincode.in API for retrieving postal code information. + /// + /// This class extends to implement API-specific behavior for + /// Postalpincode.in. Use this class to construct requests and obtain data related to Indian postal pincodes. + /// Instances can be initialized with an to customize HTTP request handling. + /// For more information about the Postal Pin Code API, see http://www.postalpincode.in/. public class PostalpincodeIn : PostcodeBaseService { public PostalpincodeIn() { } diff --git a/CoreZipCode/Services/Postcode/PostalpincodeInApi/PostalpincodeInModel.cs b/CoreZipCode/Services/Postcode/PostalpincodeInApi/PostalpincodeInModel.cs index 3787736..7a30d31 100644 --- a/CoreZipCode/Services/Postcode/PostalpincodeInApi/PostalpincodeInModel.cs +++ b/CoreZipCode/Services/Postcode/PostalpincodeInApi/PostalpincodeInModel.cs @@ -4,6 +4,13 @@ namespace CoreZipCode.Services.Postcode.PostalpincodeInApi { + /// + /// Represents the response model for postal pincode queries, containing status information, a message, and a + /// collection of post office details. + /// + /// This class is typically used to deserialize responses from postal pincode APIs. The + /// properties correspond to the expected fields in the API response, allowing access to the status, message, and + /// associated post office data. [Serializable] public class PostalpincodeInModel { @@ -17,6 +24,14 @@ public class PostalpincodeInModel public List PostOffice { get; set; } } + /// + /// Represents a postal office location and its associated details, including name, branch type, delivery status, + /// and geographic information. + /// + /// This class is typically used to model information about a post office for address validation, + /// postal lookup, or geographic categorization scenarios. All properties are read-write and correspond to standard + /// attributes found in postal systems. Instances of this class can be serialized for data exchange or storage + /// purposes. [Serializable] public class PostOffice { diff --git a/CoreZipCode/Services/Postcode/PostcodesIoApi/PostcodesIo.cs b/CoreZipCode/Services/Postcode/PostcodesIoApi/PostcodesIo.cs index a4cc671..2f687af 100644 --- a/CoreZipCode/Services/Postcode/PostcodesIoApi/PostcodesIo.cs +++ b/CoreZipCode/Services/Postcode/PostcodesIoApi/PostcodesIo.cs @@ -3,6 +3,13 @@ namespace CoreZipCode.Services.Postcode.PostcodesIoApi { + /// + /// Provides access to postcode lookup services using the Postcodes.io API. + /// + /// This class extends . Use this class to construct requests for postcode + /// information via the postcodes.io endpoint. Inherit from this class to extend or customize postcode-related operations. + /// This class is intended for use with UK postcodes and relies on an HTTP client for making API requests. For more + /// information about the Postcodes API, see https://postcodes.io. public class PostcodesIo : PostcodeBaseService { public PostcodesIo() { } diff --git a/CoreZipCode/Services/Postcode/PostcodesIoApi/PostcodesIoModel.cs b/CoreZipCode/Services/Postcode/PostcodesIoApi/PostcodesIoModel.cs index 1f475d2..d7fbf8b 100644 --- a/CoreZipCode/Services/Postcode/PostcodesIoApi/PostcodesIoModel.cs +++ b/CoreZipCode/Services/Postcode/PostcodesIoApi/PostcodesIoModel.cs @@ -4,6 +4,12 @@ namespace CoreZipCode.Services.Postcode.PostcodesIoApi { + /// + /// Represents the response model for the Postcodes.io API, containing the status code and a collection of postcode + /// results. + /// + /// This class is typically used to deserialize JSON responses from the Postcodes.io service. The + /// structure matches the standard response format returned by the API for postcode queries. [Serializable] public class PostcodesIoModel { @@ -14,6 +20,15 @@ public class PostcodesIoModel public List Result { get; set; } } + /// + /// Represents detailed information about a UK postcode, including geographic, administrative, and electoral data as + /// returned by postcode lookup services. + /// + /// This class provides structured access to various attributes associated with a postcode, such + /// as location coordinates, administrative regions, and health authorities. It is typically used to deserialize + /// responses from postcode APIs and may contain null or default values for properties where data is unavailable. + /// Thread safety is not guaranteed; if multiple threads access an instance concurrently, external synchronization + /// is required. [Serializable] public class Result { @@ -90,6 +105,14 @@ public class Result public Codes Codes { get; set; } } + /// + /// Represents a collection of administrative and geographic codes associated with a location, such as district, + /// county, ward, parish, and constituency identifiers. + /// + /// This class is typically used to provide standardized codes for various administrative + /// divisions in the United Kingdom. The codes correspond to specific government or statistical regions and can be + /// used for data integration, analysis, or mapping purposes. All properties are optional and may be null if the + /// corresponding code is not available. [Serializable] public class Codes { diff --git a/CoreZipCode/Services/ZipCode/SmartyApi/Smarty.cs b/CoreZipCode/Services/ZipCode/SmartyApi/Smarty.cs index 822b1d1..9d98785 100644 --- a/CoreZipCode/Services/ZipCode/SmartyApi/Smarty.cs +++ b/CoreZipCode/Services/ZipCode/SmartyApi/Smarty.cs @@ -5,6 +5,14 @@ namespace CoreZipCode.Services.ZipCode.SmartyApi { + /// + /// Provides access to Smarty ZIP code and street address lookup services using authenticated API requests. + /// + /// Use this class to construct authenticated requests to the Smarty US ZIP code and + /// street address APIs. The class requires valid authentication credentials, which are used to authorize each + /// request. Inherit from to enable integration with other ZIP code service implementations. This + /// class is not thread-safe; create a separate instance for each concurrent operation if needed. For more information about the Smarty API, see + /// https://www.smarty.com/. public class Smarty : ZipCodeBaseService { private const string ZipCodeSizeErrorMessage = "Invalid ZipCode Size"; diff --git a/CoreZipCode/Services/ZipCode/SmartyApi/SmartyException.cs b/CoreZipCode/Services/ZipCode/SmartyApi/SmartyException.cs index dbc5fe5..357fd8d 100644 --- a/CoreZipCode/Services/ZipCode/SmartyApi/SmartyException.cs +++ b/CoreZipCode/Services/ZipCode/SmartyApi/SmartyException.cs @@ -2,6 +2,12 @@ namespace CoreZipCode.Services.ZipCode.SmartyApi { + /// + /// Represents errors that occur during Smarty operations. + /// + /// Use this exception to indicate failures specific to Smarty functionality. This exception is + /// typically thrown when an operation cannot be completed due to invalid input, configuration issues, or other + /// conditions unique to Smarty. For general exceptions, use the base class. public class SmartyException : Exception { public SmartyException(string message) : base(message) diff --git a/CoreZipCode/Services/ZipCode/SmartyApi/SmartyModel.cs b/CoreZipCode/Services/ZipCode/SmartyApi/SmartyModel.cs index 5279fb5..4cbdcfb 100644 --- a/CoreZipCode/Services/ZipCode/SmartyApi/SmartyModel.cs +++ b/CoreZipCode/Services/ZipCode/SmartyApi/SmartyModel.cs @@ -4,6 +4,13 @@ namespace CoreZipCode.Services.ZipCode.SmartyApi { + /// + /// Represents the result of a Smarty address lookup, including input index and associated city-state and ZIP code + /// data. + /// + /// This model is typically used to deserialize responses from Smarty APIs. It contains + /// collections of city-state and ZIP code information corresponding to the input address. The class is serializable + /// and designed for use with JSON serialization frameworks. [Serializable] public class SmartyModel { @@ -17,6 +24,12 @@ public class SmartyModel public List Zipcodes { get; set; } } + /// + /// Represents a city and its associated state information, including mailing eligibility. + /// + /// This class is typically used to model address components for postal or location-based + /// operations. The properties provide both the full state name and its abbreviation, as well as an indicator of + /// whether the city is recognized for mailing purposes. public class CityState { [JsonProperty("city")] @@ -32,6 +45,13 @@ public class CityState public bool MailableCity { get; set; } } + /// + /// Represents a United States postal ZIP code and its associated geographic and administrative information. + /// + /// This class provides properties for common ZIP code attributes, including location + /// coordinates, city, county, and state details. It is typically used to model ZIP code data retrieved from + /// external sources or APIs. All properties are read-write and correspond to standard ZIP code metadata + /// fields. public class Zipcode { [JsonProperty("zipcode")] diff --git a/CoreZipCode/Services/ZipCode/SmartyApi/SmartyParamsModel.cs b/CoreZipCode/Services/ZipCode/SmartyApi/SmartyParamsModel.cs index 3ff74fe..edf3b8f 100644 --- a/CoreZipCode/Services/ZipCode/SmartyApi/SmartyParamsModel.cs +++ b/CoreZipCode/Services/ZipCode/SmartyApi/SmartyParamsModel.cs @@ -2,6 +2,12 @@ namespace CoreZipCode.Services.ZipCode.SmartyApi { + /// + /// Represents the address candidate parameters returned by the Smarty address validation API. + /// + /// This model contains detailed information about a validated address, including its components, + /// metadata, and analysis results. It is typically used to access parsed address fields and related data after a + /// Smarty address lookup operation. public class SmartyParamsModel { [JsonProperty("input_index")] @@ -29,6 +35,13 @@ public class SmartyParamsModel public Analysis Analysis { get; set; } } + /// + /// Represents the results of address analysis, including DPV (Delivery Point Validation) codes and related status + /// indicators. + /// + /// This class provides properties for various USPS DPV analysis codes and flags, which can be + /// used to interpret the deliverability and status of an address. The property values correspond to codes returned + /// by address validation services and may require reference to USPS documentation for detailed meaning. public class Analysis { [JsonProperty("dpv_match_code")] @@ -47,6 +60,14 @@ public class Analysis public string Active { get; set; } } + /// + /// Represents the individual address components for a United States postal address, including street, city, state, + /// and ZIP code information. + /// + /// This class provides structured properties for each part of an address, which can be used for + /// address parsing, validation, or formatting. All properties correspond to standard USPS address fields and are + /// mapped to their respective JSON keys for serialization and deserialization. Property values may be null or empty + /// if the corresponding address component is not available. public class Components { [JsonProperty("primary_number")] @@ -80,6 +101,15 @@ public class Components public string DeliveryPointCheckDigit { get; set; } } + /// + /// Represents supplemental metadata information for a geographic or postal record, including location, + /// administrative, and delivery details. + /// + /// The properties of this class provide access to various attributes such as record type, ZIP + /// code type, county information, carrier route, congressional district, residential delivery indicator (RDI), + /// enhanced line of travel (eLOT) data, geographic coordinates, time zone, and daylight saving time status. This + /// class is typically used to enrich address or location data with additional context for validation, analysis, or + /// delivery optimization scenarios. public class Metadata { [JsonProperty("record_type")] diff --git a/CoreZipCode/Services/ZipCode/ViaCepApi/ViaCep.cs b/CoreZipCode/Services/ZipCode/ViaCepApi/ViaCep.cs index f031d7f..c5610e1 100644 --- a/CoreZipCode/Services/ZipCode/ViaCepApi/ViaCep.cs +++ b/CoreZipCode/Services/ZipCode/ViaCepApi/ViaCep.cs @@ -4,6 +4,13 @@ namespace CoreZipCode.Services.ZipCode.ViaCepApi { + /// + /// Provides an implementation of a zip code lookup service using the ViaCep API for Brazilian addresses. + /// + /// ViaCep enables retrieval of address information based on zip code, state, city, and street + /// parameters. This class extends to construct ViaCep-specific request URLs. Use this service to + /// integrate Brazilian postal code queries into your application. For more information about the ViaCep API, see + /// https://viacep.com.br. public class ViaCep : ZipCodeBaseService { private const string ZipCodeSizeErrorMessage = "Invalid ZipCode Size"; diff --git a/CoreZipCode/Services/ZipCode/ViaCepApi/ViaCepAddressModel.cs b/CoreZipCode/Services/ZipCode/ViaCepApi/ViaCepAddressModel.cs index 0427a06..a2cd313 100644 --- a/CoreZipCode/Services/ZipCode/ViaCepApi/ViaCepAddressModel.cs +++ b/CoreZipCode/Services/ZipCode/ViaCepApi/ViaCepAddressModel.cs @@ -3,6 +3,13 @@ namespace CoreZipCode.Services.ZipCode.ViaCepApi { + /// + /// Represents an address as returned by the ViaCep API, including postal code, street information, and regional + /// identifiers. + /// + /// This model is typically used to deserialize address data from the ViaCep web service, which + /// provides postal code lookup for Brazilian addresses. All properties correspond to fields in the ViaCep API + /// response. This class is serializable and suitable for use in data transfer scenarios. [Serializable] public class ViaCepAddressModel { diff --git a/CoreZipCode/Services/ZipCode/ViaCepApi/ViaCepException.cs b/CoreZipCode/Services/ZipCode/ViaCepApi/ViaCepException.cs index 9c7133c..354c927 100644 --- a/CoreZipCode/Services/ZipCode/ViaCepApi/ViaCepException.cs +++ b/CoreZipCode/Services/ZipCode/ViaCepApi/ViaCepException.cs @@ -2,6 +2,12 @@ namespace CoreZipCode.Services.ZipCode.ViaCepApi { + /// + /// Represents errors that occur when interacting with the ViaCep API. + /// + /// Use this exception to identify and handle failures specific to ViaCep operations, such as + /// invalid responses or connectivity issues. This exception is typically thrown when the ViaCep service returns an + /// error or cannot be reached. For general exceptions, use the base class. public class ViaCepException : Exception { public ViaCepException(string message) : base(message) diff --git a/README.md b/README.md index e2e0571..5afe5ab 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# ![CoreZipCode](./corezipcode.png) +# ![CoreZipCode](./docs/images/corezipcode.png) [![Build](https://github.com/danilolutz/CoreZipCode/actions/workflows/main.yml/badge.svg)](https://github.com/danilolutz/CoreZipCode/actions/workflows/main.yml) [![Coverage Status](https://coveralls.io/repos/github/danilolutz/CoreZipCode/badge.svg?branch=master)](https://coveralls.io/github/danilolutz/CoreZipCode?branch=master) @@ -10,7 +10,7 @@ Normaly we must implement ZipCode or Postcode services every time in each new software we create. Well this package is for keep you [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) and eliminate the necessity to implement ZipCode or Postcode services over and over. -Also this package could be used for easily implements address services to yours [Microsoft .Net Core](https://dotnet.github.io/) based software. +Also this package could be used for easily implements address services to yours [Microsoft .NET](https://dotnet.github.io/) based software. And the **CoreZipCode** was designed to be easily extensible, and if you want, implement your own address services, you only must override the API calls methods. diff --git a/corezipcode.svg b/corezipcode.svg deleted file mode 100644 index d9d4fa4..0000000 --- a/corezipcode.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/docfx.json b/docs/docfx.json new file mode 100644 index 0000000..e040e2b --- /dev/null +++ b/docs/docfx.json @@ -0,0 +1,60 @@ +{ + "$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json", + "metadata": [ + { + "src": [ + { + "src": "../CoreZipCode", + "files": [ + "**/*.csproj" + ], + "exclude": [ "**/bin/**", "**/obj/**" ] + } + ], + "output": "api", + "outputFormat": "apiPage" + } + ], + "build": { + "content": [ + { + "files": [ + "**/*.{md,yml}" + ], + "exclude": [ + "_site/**" + ] + } + ], + "resource": [ + { + "files": [ + "images/**" + ] + } + ], + "output": "_site", + "template": [ + "default", + "modern", + "template" + ], + "globalMetadata": { + "_appName": "", + "_appTitle": "CoreZipCode", + "_appFooter": "CoreZipCode Docs", + "_appLogoPath": "images/corezipcode128.png", + "_appFaviconPath": "images/favicon.ico", + "_enableSearch": true, + "_gitContribute": { + "repo": "https://github.com/danilolutz/CoreZipCode" + }, + "pdf": false + }, + "sitemap": { + "baseUrl": "https://danilolutz.dev/CoreZipCode", + "priority": 0.5, + "changefreq": "daily" + } + } +} \ No newline at end of file diff --git a/docs/docs/extending-corezipcode.md b/docs/docs/extending-corezipcode.md new file mode 100644 index 0000000..873f30f --- /dev/null +++ b/docs/docs/extending-corezipcode.md @@ -0,0 +1,27 @@ +# Extending CoreZipCode + +You can extends `ZipCodeBaseService` abstract class and create your own implementation of your prefered address service. Like below: + +```CSharp +using CoreZipCode.Interfaces; + +namespace CoreZipCode.Services.YourService +{ + public class YourService : ZipCodeBaseService + { + public override string SetZipCodeUrl(string zipcode) + { + // You can implement some validation method here. + return $"https://yourservice.com/{zipcode}/json/"; + } + + public override string SetZipCodeUrlBy(string state, string city, string street) + { + // You can implement some validation method here. + return $"https://yourservice.com/{state}/{city}/{street}/json/"; + } + } +} +``` + +> **NOTE**: Same principles are used to extends postcode lookups (`PostCodeBaseService`). \ No newline at end of file diff --git a/docs/docs/introduction.md b/docs/docs/introduction.md new file mode 100644 index 0000000..85ce473 --- /dev/null +++ b/docs/docs/introduction.md @@ -0,0 +1,23 @@ +# Introduction + +Normaly we must implement ZipCode or Postcode services every time in each new software we create. Well this package is for keep you [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) and eliminate the necessity to implement ZipCode or Postcode services over and over. + +Also this package could be used for easily implements address services to yours [Microsoft .NET](https://dotnet.github.io/) based software. + +And the **CoreZipCode** was designed to be easily extensible, and if you want, implement your own address services, you only must override the API calls methods. + +## Concept and flow + +- `*BaseService` are classes with reusable predefined methods. +- `ApiHandler` is a `HttpClient` adapter witch is consumed by `*BaseService` classes. + +A step-by-step guide: + +1. `CustomZipCodeService` extends `ZipCodeBaseService` and define how API URLs must be treated via abstract methods. +2. `ZipCodeBaseService` builds the URL and execute some validations (or not, it's up to you). +3. `ZipCodeBaseService` calls `ApiHandler`, witch do a request to external desired API and do some response validations. + +Nothing like a diagram to simplify the explanation: + +![CoreZipCode flow](../images/flow.svg) + diff --git a/docs/docs/toc.yml b/docs/docs/toc.yml new file mode 100644 index 0000000..d5685c7 --- /dev/null +++ b/docs/docs/toc.yml @@ -0,0 +1,6 @@ +- name: Get started +- href: ../index.md +- href: introduction.md + +- name: Extending +- href: extending-corezipcode.md \ No newline at end of file diff --git a/corezipcode.png b/docs/images/corezipcode.png similarity index 100% rename from corezipcode.png rename to docs/images/corezipcode.png diff --git a/docs/images/corezipcode.svg b/docs/images/corezipcode.svg new file mode 100644 index 0000000..15b1ad0 --- /dev/null +++ b/docs/images/corezipcode.svg @@ -0,0 +1,121 @@ + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/corezipcode128.png b/docs/images/corezipcode128.png similarity index 100% rename from corezipcode128.png rename to docs/images/corezipcode128.png diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico new file mode 100644 index 0000000..b5cb8ef Binary files /dev/null and b/docs/images/favicon.ico differ diff --git a/docs/images/flow.excalidraw b/docs/images/flow.excalidraw new file mode 100644 index 0000000..13f6de6 --- /dev/null +++ b/docs/images/flow.excalidraw @@ -0,0 +1,482 @@ +{ + "type": "excalidraw", + "version": 2, + "source": "https://excalidraw.com", + "elements": [ + { + "id": "e5wDF8rqvzBS7f4G_dntm", + "type": "rectangle", + "x": 379, + "y": 271, + "width": 225, + "height": 83.99999999999999, + "angle": 0, + "strokeColor": "#f08c00", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "index": "a0", + "roundness": { + "type": 3 + }, + "seed": 1062004592, + "version": 79, + "versionNonce": 805626768, + "isDeleted": false, + "boundElements": [ + { + "type": "text", + "id": "HJsv5_DppPHgM5OG2EgIq" + }, + { + "id": "FURZRndKnBikW-iwPuj7t", + "type": "arrow" + } + ], + "updated": 1764016318529, + "link": null, + "locked": false + }, + { + "id": "HJsv5_DppPHgM5OG2EgIq", + "type": "text", + "x": 404.2920684814453, + "y": 303, + "width": 174.41586303710938, + "height": 20, + "angle": 0, + "strokeColor": "#f08c00", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "index": "a1", + "roundness": null, + "seed": 708428688, + "version": 80, + "versionNonce": 1775820144, + "isDeleted": false, + "boundElements": null, + "updated": 1764016318529, + "link": null, + "locked": false, + "text": "CustomZipCodeService", + "fontSize": 16, + "fontFamily": 5, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": "e5wDF8rqvzBS7f4G_dntm", + "originalText": "CustomZipCodeService", + "autoResize": true, + "lineHeight": 1.25 + }, + { + "id": "cXlYCwRvKFksEpkAVkhK8", + "type": "rectangle", + "x": 697.6666666666667, + "y": 271, + "width": 225, + "height": 83.99999999999999, + "angle": 0, + "strokeColor": "#f08c00", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "index": "a2", + "roundness": { + "type": 3 + }, + "seed": 1773596016, + "version": 129, + "versionNonce": 686564208, + "isDeleted": false, + "boundElements": [ + { + "type": "text", + "id": "KpHndmvrbRJVRXP-cYr1-" + }, + { + "id": "FURZRndKnBikW-iwPuj7t", + "type": "arrow" + }, + { + "id": "ow3N5pAOyCT3ZLHe1ibj6", + "type": "arrow" + } + ], + "updated": 1764016321819, + "link": null, + "locked": false + }, + { + "id": "KpHndmvrbRJVRXP-cYr1-", + "type": "text", + "x": 731.9107233683269, + "y": 303, + "width": 156.5118865966797, + "height": 20, + "angle": 0, + "strokeColor": "#f08c00", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "index": "a3", + "roundness": null, + "seed": 290963312, + "version": 126, + "versionNonce": 1702117744, + "isDeleted": false, + "boundElements": [], + "updated": 1764016320256, + "link": null, + "locked": false, + "text": "ZipCodeBaseService", + "fontSize": 16, + "fontFamily": 5, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": "cXlYCwRvKFksEpkAVkhK8", + "originalText": "ZipCodeBaseService", + "autoResize": true, + "lineHeight": 1.25 + }, + { + "id": "xIeq6swFqdFH7bQUbVcIB", + "type": "rectangle", + "x": 1015.3333333333334, + "y": 271, + "width": 225, + "height": 83.99999999999999, + "angle": 0, + "strokeColor": "#f08c00", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "index": "a4", + "roundness": { + "type": 3 + }, + "seed": 1864759696, + "version": 81, + "versionNonce": 1835501968, + "isDeleted": false, + "boundElements": [ + { + "type": "text", + "id": "JXVpV3anxk0D8GSBsSkrh" + }, + { + "id": "ow3N5pAOyCT3ZLHe1ibj6", + "type": "arrow" + }, + { + "id": "nfa8EXJAZdcLJtPxsWo9_", + "type": "arrow" + } + ], + "updated": 1764016323848, + "link": null, + "locked": false + }, + { + "id": "JXVpV3anxk0D8GSBsSkrh", + "type": "text", + "x": 1088.5453618367515, + "y": 303, + "width": 78.57594299316406, + "height": 20, + "angle": 0, + "strokeColor": "#f08c00", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "index": "a5", + "roundness": null, + "seed": 156256144, + "version": 84, + "versionNonce": 635148144, + "isDeleted": false, + "boundElements": [], + "updated": 1764016323848, + "link": null, + "locked": false, + "text": "ApiHandler", + "fontSize": 16, + "fontFamily": 5, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": "xIeq6swFqdFH7bQUbVcIB", + "originalText": "ApiHandler", + "autoResize": true, + "lineHeight": 1.25 + }, + { + "id": "XqHzdSW4ipqbf44eDjSHD", + "type": "text", + "x": 1330, + "y": 289, + "width": 169, + "height": 50, + "angle": 0, + "strokeColor": "#2f9e44", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "index": "a6", + "roundness": null, + "seed": 2030272400, + "version": 70, + "versionNonce": 740189584, + "isDeleted": false, + "boundElements": [ + { + "id": "nfa8EXJAZdcLJtPxsWo9_", + "type": "arrow" + } + ], + "updated": 1764016327715, + "link": null, + "locked": false, + "text": "External Desired\nAPI", + "fontSize": 20, + "fontFamily": 5, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "External Desired API", + "autoResize": false, + "lineHeight": 1.25 + }, + { + "id": "FURZRndKnBikW-iwPuj7t", + "type": "arrow", + "x": 609, + "y": 312.9, + "width": 83.66666666666674, + "height": 5.684341886080802e-14, + "angle": 0, + "strokeColor": "#f08c00", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "index": "a8", + "roundness": null, + "seed": 1588790672, + "version": 117, + "versionNonce": 803525008, + "isDeleted": false, + "boundElements": null, + "updated": 1764016321820, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 83.66666666666674, + 5.684341886080802e-14 + ] + ], + "lastCommittedPoint": null, + "startBinding": { + "elementId": "e5wDF8rqvzBS7f4G_dntm", + "focus": -0.002380952380952637, + "gap": 5, + "fixedPoint": [ + 1.0222222222222221, + 0.49880952380952365 + ] + }, + "endBinding": { + "elementId": "cXlYCwRvKFksEpkAVkhK8", + "focus": 0.0023809523809521934, + "gap": 5, + "fixedPoint": [ + -0.022222222222222223, + 0.4988095238095243 + ] + }, + "startArrowhead": null, + "endArrowhead": "arrow", + "elbowed": true, + "fixedSegments": null, + "startIsSpecial": null, + "endIsSpecial": null + }, + { + "id": "ow3N5pAOyCT3ZLHe1ibj6", + "type": "arrow", + "x": 927.6666666666666, + "y": 312.9, + "width": 82.66666666666674, + "height": 0, + "angle": 0, + "strokeColor": "#f08c00", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "index": "a9", + "roundness": null, + "seed": 1834837872, + "version": 193, + "versionNonce": 2087985040, + "isDeleted": false, + "boundElements": [], + "updated": 1764016321821, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 82.66666666666674, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": { + "elementId": "cXlYCwRvKFksEpkAVkhK8", + "focus": -0.0023809523809521934, + "gap": 4.999999999999886, + "fixedPoint": [ + 1.0222222222222217, + 0.49880952380952365 + ] + }, + "endBinding": { + "elementId": "xIeq6swFqdFH7bQUbVcIB", + "focus": 0.0023809523809539676, + "gap": 5, + "fixedPoint": [ + -0.022222222222222223, + 0.49880952380952365 + ] + }, + "startArrowhead": null, + "endArrowhead": "arrow", + "elbowed": true, + "fixedSegments": null, + "startIsSpecial": null, + "endIsSpecial": null + }, + { + "id": "nfa8EXJAZdcLJtPxsWo9_", + "type": "arrow", + "x": 1245.3333333333335, + "y": 312.9, + "width": 79.66666666666652, + "height": 0.8499999999999659, + "angle": 0, + "strokeColor": "#f08c00", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "index": "aB", + "roundness": null, + "seed": 333303664, + "version": 168, + "versionNonce": 1441377680, + "isDeleted": false, + "boundElements": [], + "updated": 1764016321821, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 79.66666666666652, + 0.8499999999999659 + ] + ], + "lastCommittedPoint": null, + "startBinding": { + "elementId": "xIeq6swFqdFH7bQUbVcIB", + "focus": -0.0023809523809521934, + "gap": 5, + "fixedPoint": [ + 1.0222222222222228, + 0.49880952380952365 + ] + }, + "endBinding": { + "elementId": "XqHzdSW4ipqbf44eDjSHD", + "focus": 0.01000000000000035, + "gap": 5, + "fixedPoint": [ + -0.029585798816568046, + 0.4949999999999989 + ] + }, + "startArrowhead": null, + "endArrowhead": "arrow", + "elbowed": true, + "fixedSegments": null, + "startIsSpecial": null, + "endIsSpecial": null + } + ], + "appState": { + "gridSize": 20, + "gridStep": 5, + "gridModeEnabled": false, + "viewBackgroundColor": "#ffffff", + "lockedMultiSelections": {} + }, + "files": {} +} \ No newline at end of file diff --git a/docs/images/flow.png b/docs/images/flow.png new file mode 100644 index 0000000..a6bbb96 Binary files /dev/null and b/docs/images/flow.png differ diff --git a/docs/images/flow.svg b/docs/images/flow.svg new file mode 100644 index 0000000..cd370fd --- /dev/null +++ b/docs/images/flow.svg @@ -0,0 +1,4 @@ + + +CustomZipCodeServiceZipCodeBaseServiceApiHandlerExternal DesiredAPI \ No newline at end of file diff --git a/docs/images/pin.png b/docs/images/pin.png new file mode 100644 index 0000000..6e3bf71 Binary files /dev/null and b/docs/images/pin.png differ diff --git a/docs/images/pin.svg b/docs/images/pin.svg new file mode 100644 index 0000000..21684b2 --- /dev/null +++ b/docs/images/pin.svg @@ -0,0 +1,51 @@ + + + + + + + + + + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..c99e306 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,53 @@ +# Quick Start + +You can download the code and build it by yourself or you can install by [Nuget](https://www.nuget.org) package in: [CoreZipCode Package](https://www.nuget.org/packages/CoreZipCode/). + +Just in case if you doesn't want leave GitHub at this moment: + +```bash +dotnet add package CoreZipCode +``` + +## Quickest example + +After you decide how you'll get the CoreZipCode, just inject (e.g.: [Simple Injector](https://simpleinjector.org/)) and use it. + +```CSharp +using CoreZipCode.Interfaces; + +namespace YourProject +{ + public YourClass + { + private readonly ZipCodeBaseService _coreZipCode; + + public YourClass(ZipCodeBaseService coreZipCode) + { + _coreZipCode = coreZipCode; + } + + public void YourMethod() + { + var addressByZipCode = _coreZipCode.Execute("14810100"); + var zipCodeByAddress = _coreZipCode.Execute("sp", "araraquara", "barão do rio"); + + // Generic type return was added in version 1.1.0 + var addressByZipCodeObject = _coreZipCode.GetAddress("14810100"); + var zipCodeByAddressObjectList = _coreZipCode.ListAddresses("sp", "araraquara", "barão do rio"); + } + + // Async methods introduced in 1.1.0 + public async void YourMethodAsync() + { + var addressByZipCode = await _coreZipCode.ExecuteAsync("14810100"); + var zipCodeByAddress = await _coreZipCode.ExecuteAsync("sp", "araraquara", "barão do rio"); + + // Generic type return. + var addressByZipCodeObject = await _coreZipCode.GetAddressAsync("14810100"); + var zipCodeByAddressObjectList = await _coreZipCode.ListAddressesAsync("sp", "araraquara", "barão do rio"); + } + } +} +``` + +You can check [Program.cs](https://github.com/danilolutz/CoreZipCode/blob/main/SampleApp/Program.cs) to more robust example. diff --git a/docs/template/public/main.css b/docs/template/public/main.css new file mode 100644 index 0000000..e0eb485 --- /dev/null +++ b/docs/template/public/main.css @@ -0,0 +1,4 @@ +body { + --bs-link-color-rgb: 66, 184, 131 !important; + --bs-link-hover-color-rgb: 64, 180, 128 !important; +} \ No newline at end of file diff --git a/docs/template/public/main.js b/docs/template/public/main.js new file mode 100644 index 0000000..7170361 --- /dev/null +++ b/docs/template/public/main.js @@ -0,0 +1,9 @@ +export default { + iconLinks: [ + { + icon: 'github', + href: 'https://github.com/danilolutz/CoreZipCode', + title: 'GitHub' + } + ] +} \ No newline at end of file diff --git a/docs/toc.yml b/docs/toc.yml new file mode 100644 index 0000000..061acc6 --- /dev/null +++ b/docs/toc.yml @@ -0,0 +1,4 @@ +- name: Docs + href: docs/ +- name: API + href: api/ \ No newline at end of file