Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jaxelr/nancy.metadata.openapi
Open Api Spec library for NancyFx
https://github.com/jaxelr/nancy.metadata.openapi
metadata nancyfx openapi
Last synced: 6 days ago
JSON representation
Open Api Spec library for NancyFx
- Host: GitHub
- URL: https://github.com/jaxelr/nancy.metadata.openapi
- Owner: Jaxelr
- License: mit
- Created: 2017-06-01T00:59:34.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-01-25T15:34:54.000Z (10 months ago)
- Last Synced: 2024-10-06T22:35:44.151Z (about 1 month ago)
- Topics: metadata, nancyfx, openapi
- Language: C#
- Homepage:
- Size: 49 MB
- Stars: 8
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Nancy.Metadata.OpenApi [![Mit License][mit-img]][mit]
This library extends Nancy modules in order to produce a specification file that will follow the OpenAPI spec.
You can find the latest specifications of [OpenAPI here](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md)
This library targets Nancy 2.0, for previous versions that target Nancy 1.X check release that target version 0.7.0 and below.
__Note:__ Since Nancyfx is no longer being maintained i will be deprioritizing this library, please read [here for details](https://github.com/NancyFx/Nancy/issues/3010)
## Builds
| Appveyor | Branch | Coverage |
| :---: | :---: | :--: |
| [![Build status][build-master-img]][build-master] | master | [![CodeCov][codecov-master-img]][codecov-master] |
| [![Build status][build-develop-img]][build-develop] | develop | [![CodeCov][codecov-develop-img]][codecov-develop] |
## Packages
NuGet (Stable) | MyGet (Prerelease)
:---: | :---:
[![NuGet][nuget-img]][nuget] | [![MyGet][myget-img]][myget] |
## Installation
Via nuget:
``` powershell
PM> Install-Package Nancy.Metadata.OpenApi
```
You also need the Metadata library provided by Nancyfx:
``` powershell
PM> Install-Package Nancy.Metadata.Modules
```
## Usage
Define a docs module that will serve our OpenApi Json (currently only json is supported) document:
```c#
using Nancy.Metadata.OpenApi.Model;
using Nancy.Metadata.OpenApi.Modules;
public class DocsModule : OpenApiDocsModuleBase //We must inherit from the OpenApiDocsModuleBase
{
//Could be an array of Servers corresponding to different environments.
public static Server Server
=> new Server() { Description = "My Descripton", Url = "http://localhost:5000/" };
public static string[] Tags => new string[] { "sample", "openapi" };
public DocsModule(IRouteCacheProvider routeCacheProvider) :
base(routeCacheProvider,
"/api/docs/openapi.json", //Document location path
"My API ", //Api Title
"v1.0", //Version of the Api
Server,
"/api", //Base url
Tags) //Document Tags
{
}
}
```
We could optionally, if the information is needed, add Contact, License and External Docs information:
```c#
public class DocsModule : OpenApiDocsModuleBase //We must inherit from the OpenApiDocsModuleBase
{
public static Server Server
=> new Server() { Description = "My Descripton", Url = "http://localhost:5001/" };
public static string[] Tags => new string[] { "sample", "openapi" };
public DocsModule(IRouteCacheProvider routeCacheProvider) :
base(routeCacheProvider, "/api/docs/openapi.json", "My API 2", "v1.1", Server, "/api", Tags)
{
//Optional information.
WithContact("Contact Information", "[email protected]", "https://jaxelr.github.io");
//Optional information.
WithLicense("MIT", "https://opensource.org/licenses/MIT");
//Optional Information.
WithExternalDocument("This is a tutorial or a spec doc.", "https://jaxelr.github.io")
}
}
```
Then, define the Nancy modules as you would usually do:
```c#
//Example using Nancy v2
public class MyModule : NancyModule
{
public MyModule() : base("/api")
{
Get("/hello", r => HelloWorld(), name: "SimpleRequest");
Get("/hello/{name}", r => Hello(r.name), name: "SimpleRequestWithParameter");
}
}
//Skipped method implementations for brevity sake...
```
Finally, you must define the metadata of the operations. To do so, simply declare the metadata module (using Nancy.Metadata.Modules) on the same namespace as the endpoint operations were defined, using the inherited MetadataModule class and the OpenApiRouteMetadata class defined on Nancy.Metadata.OpenApi.Core.
```c#
using Nancy.Metadata.Modules;
using Nancy.Metadata.OpenApi.Core;
using Nancy.Metadata.OpenApi.Fluent;
public class MyMetadataModule : MetadataModule
{
public MyMetadataModule()
{
Describe["SimpleRequest"] = desc => new OpenApiRouteMetadata(desc)
.With(i => i.WithResponseModel("200", typeof(SimpleResponseModel), "Sample response")
.WithSummary("Simple GET example"));
Describe["SimpleRequestWithParameter"] = desc => new OpenApiRouteMetadata(desc)
.With(i => i.WithResponseModel("200", typeof(SimpleResponseModel), "Sample response")
.WithRequestParameter("name")
.WithSummary("Simple GET with parameters"));
}
}
```
Thats pretty much it, the docs endpoint defined above would generate some valid OpenApi Json. You can validate the Open Api endpoint using [swagger-ui](https://github.com/swagger-api/swagger-ui). (For those unaware, OpenApi used to be called Swagger, so any reference to Swagger usually means version <= 2.0) Check the [Compatibility table](https://github.com/swagger-api/swagger-ui#compatibility) of UI for usage.
For a working example, see the sample app that uses the Swagger-UI site as a validator.
## Contributing
Check the [guidelines](https://github.com/Jaxelr/Nancy.Metadata.OpenApi/blob/master/.github/CONTRIBUTING.md) for a simple explanation on how you could contribute.
[mit-img]: http://img.shields.io/badge/License-MIT-blue.svg
[mit]: https://github.com/Jaxelr/Nancy.Metadata.OpenApi/blob/master/LICENSE
[build-master-img]: https://ci.appveyor.com/api/projects/status/bk8fiqknunkegnv7/branch/master?svg=true
[build-master]: https://ci.appveyor.com/project/Jaxelr/nancy-metadata-openapi/branch/master
[build-develop-img]: https://ci.appveyor.com/api/projects/status/bk8fiqknunkegnv7/branch/develop?svg=true
[build-develop]: https://ci.appveyor.com/project/Jaxelr/nancy-metadata-openapi/branch/develop
[codecov-master-img]: https://codecov.io/gh/Jaxelr/Nancy.Metadata.OpenApi/branch/master/graph/badge.svg
[codecov-master]: https://codecov.io/gh/Jaxelr/Nancy.Metadata.OpenApi/branch/master
[codecov-develop-img]: https://codecov.io/gh/Jaxelr/Nancy.Metadata.OpenApi/branch/develop/graph/badge.svg
[codecov-develop]: https://codecov.io/gh/Jaxelr/Nancy.Metadata.OpenApi/branch/develop
[build-img]: https://ci.appveyor.com/api/projects/status/bk8fiqknunkegnv7?svg=true
[nuget]: https://www.nuget.org/packages/Nancy.Metadata.OpenApi
[nuget-img]: https://img.shields.io/nuget/v/Nancy.Metadata.OpenApi.svg
[myget]: https://www.myget.org/feed/nancy-metadata-openapi/package/nuget/Nancy.Metadata.OpenApi
[myget-img]: https://img.shields.io/myget/nancy-metadata-openapi/v/Nancy.Metadata.OpenApi.svg