mirror of https://github.com/Squidex/squidex.git
Browse Source
* #639 Create JSON schemas for all rule events * Fixes the OpenAPI schema and simplifies the code. Closes #644pull/653/head
Sebastian Stehle
5 years ago
committed by
GitHub
GitHub
11 changed files with 442 additions and 171 deletions
@ -1,6 +0,0 @@ |
|||
The data of the content to be created or updated. |
|||
|
|||
Please note that each field is an object with one entry per language. |
|||
If the field is not localizable you must use `iv` (invariant language) as a key. |
|||
|
|||
Read more about it at: https://docs.squidex.io/04-guides/02-api.html |
|||
@ -1,27 +0,0 @@ |
|||
How to make queries? |
|||
|
|||
Read more about it at: https://docs.squidex.io/04-guides/02-api.html |
|||
|
|||
The query endpoints support three options: |
|||
|
|||
### Query with OData |
|||
|
|||
Squidex supports a subset of the OData (https://www.odata.org/) syntax with with the following query options: |
|||
|
|||
* **$top**: The $top query option requests the number of items in the queried collection to be included in the result. The default value is 20 and the maximum allowed value is 200. You can change the maximum in the app settings, when you host Squidex yourself. |
|||
* **$skip**: The $skip query option requests the number of items in the queried collection that are to be skipped and not included in the result. Use it together with $top to read the all your data page by page. |
|||
* **$search**: The $search query option allows clients to request entities matching a free-text search expression. We add the data of all fields for all languages to our full text engine. |
|||
* **$filter**: The $filter query option allows clients to filter a collection of resources that are addressed by a request URL. |
|||
* **$orderby**: The $orderby query option allows clients to request resources in a particular order. |
|||
|
|||
### Query with JSON query |
|||
|
|||
Squidex also supports a query syntax based on JSON. You have to pass in the query object as query parameter: |
|||
|
|||
* **q**: A json text that represents the same query options as with OData, but is more performant to parse. |
|||
|
|||
### Query by IDs |
|||
|
|||
Query your items by passing in one or many IDs with the following query parameter: |
|||
|
|||
* **ids**: A comma-separated list of ids. If you define this option all other settings are ignored. |
|||
@ -1,15 +0,0 @@ |
|||
Squidex uses oauth2 client authentication. Read more about it at: https://oauth.net/2/ and https://tools.ietf.org/html/rfc6750. |
|||
|
|||
To retrieve an access token, the client id must make a request to the token url. For example: |
|||
|
|||
$ curl |
|||
-X POST '<TOKEN_URL>' |
|||
-H 'Content-Type: application/x-www-form-urlencoded' |
|||
-d 'grant_type=client_credentials& |
|||
client_id=[CLIENT_ID]& |
|||
client_secret=[CLIENT_SECRET]& |
|||
scope=squidex-api' |
|||
|
|||
You must send this token in the `Authorization` header when making requests to the API: |
|||
|
|||
Authorization: Bearer <token> |
|||
@ -1,74 +0,0 @@ |
|||
// ==========================================================================
|
|||
// Squidex Headless CMS
|
|||
// ==========================================================================
|
|||
// Copyright (c) Squidex UG (haftungsbeschränkt)
|
|||
// All rights reserved. Licensed under the MIT license.
|
|||
// ==========================================================================
|
|||
|
|||
using System; |
|||
using System.Collections.Generic; |
|||
using System.IO; |
|||
using Microsoft.AspNetCore.Http; |
|||
using NJsonSchema; |
|||
using NSwag; |
|||
|
|||
namespace Squidex.Pipeline.OpenApi |
|||
{ |
|||
public static class OpenApiHelper |
|||
{ |
|||
public static readonly string SecurityDocs = LoadDocs("security"); |
|||
|
|||
public static readonly string SchemaBodyDocs = LoadDocs("schema-body"); |
|||
|
|||
public static readonly string SchemaQueryDocs = LoadDocs("schema-query"); |
|||
|
|||
private static string LoadDocs(string name) |
|||
{ |
|||
var assembly = typeof(OpenApiHelper).Assembly; |
|||
|
|||
using (var resourceStream = assembly.GetManifestResourceStream($"Squidex.Docs.{name}.md")) |
|||
{ |
|||
using (var streamReader = new StreamReader(resourceStream!)) |
|||
{ |
|||
return streamReader.ReadToEnd(); |
|||
} |
|||
} |
|||
} |
|||
|
|||
public static OpenApiDocument CreateApiDocument(HttpContext context, string appName) |
|||
{ |
|||
var scheme = |
|||
string.Equals(context.Request.Scheme, "http", StringComparison.OrdinalIgnoreCase) ? |
|||
OpenApiSchema.Http : |
|||
OpenApiSchema.Https; |
|||
|
|||
var document = new OpenApiDocument |
|||
{ |
|||
Schemes = new List<OpenApiSchema> |
|||
{ |
|||
scheme |
|||
}, |
|||
Consumes = new List<string> |
|||
{ |
|||
"application/json" |
|||
}, |
|||
Produces = new List<string> |
|||
{ |
|||
"application/json" |
|||
}, |
|||
Info = new OpenApiInfo |
|||
{ |
|||
Title = $"Squidex API for {appName} App" |
|||
}, |
|||
SchemaType = SchemaType.OpenApi3 |
|||
}; |
|||
|
|||
if (!string.IsNullOrWhiteSpace(context.Request.Host.Value)) |
|||
{ |
|||
document.Host = context.Request.Host.Value; |
|||
} |
|||
|
|||
return document; |
|||
} |
|||
} |
|||
} |
|||
@ -0,0 +1,132 @@ |
|||
//------------------------------------------------------------------------------
|
|||
// <auto-generated>
|
|||
// This code was generated by a tool.
|
|||
// Runtime Version:4.0.30319.42000
|
|||
//
|
|||
// Changes to this file may cause incorrect behavior and will be lost if
|
|||
// the code is regenerated.
|
|||
// </auto-generated>
|
|||
//------------------------------------------------------------------------------
|
|||
|
|||
namespace Squidex.Properties { |
|||
using System; |
|||
|
|||
|
|||
/// <summary>
|
|||
/// A strongly-typed resource class, for looking up localized strings, etc.
|
|||
/// </summary>
|
|||
// This class was auto-generated by the StronglyTypedResourceBuilder
|
|||
// class via a tool like ResGen or Visual Studio.
|
|||
// To add or remove a member, edit your .ResX file then rerun ResGen
|
|||
// with the /str option, or rebuild your VS project.
|
|||
[global::System.CodeDom.Compiler.GeneratedCodeAttribute("System.Resources.Tools.StronglyTypedResourceBuilder", "16.0.0.0")] |
|||
[global::System.Diagnostics.DebuggerNonUserCodeAttribute()] |
|||
[global::System.Runtime.CompilerServices.CompilerGeneratedAttribute()] |
|||
internal class Resources { |
|||
|
|||
private static global::System.Resources.ResourceManager resourceMan; |
|||
|
|||
private static global::System.Globalization.CultureInfo resourceCulture; |
|||
|
|||
[global::System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("Microsoft.Performance", "CA1811:AvoidUncalledPrivateCode")] |
|||
internal Resources() { |
|||
} |
|||
|
|||
/// <summary>
|
|||
/// Returns the cached ResourceManager instance used by this class.
|
|||
/// </summary>
|
|||
[global::System.ComponentModel.EditorBrowsableAttribute(global::System.ComponentModel.EditorBrowsableState.Advanced)] |
|||
internal static global::System.Resources.ResourceManager ResourceManager { |
|||
get { |
|||
if (object.ReferenceEquals(resourceMan, null)) { |
|||
global::System.Resources.ResourceManager temp = new global::System.Resources.ResourceManager("Squidex.Properties.Resources", typeof(Resources).Assembly); |
|||
resourceMan = temp; |
|||
} |
|||
return resourceMan; |
|||
} |
|||
} |
|||
|
|||
/// <summary>
|
|||
/// Overrides the current thread's CurrentUICulture property for all
|
|||
/// resource lookups using this strongly typed resource class.
|
|||
/// </summary>
|
|||
[global::System.ComponentModel.EditorBrowsableAttribute(global::System.ComponentModel.EditorBrowsableState.Advanced)] |
|||
internal static global::System.Globalization.CultureInfo Culture { |
|||
get { |
|||
return resourceCulture; |
|||
} |
|||
set { |
|||
resourceCulture = value; |
|||
} |
|||
} |
|||
|
|||
/// <summary>
|
|||
/// Looks up a localized string similar to # Introduction
|
|||
///
|
|||
///The API provides two specifications. The Content API usually returns one object per schema field where the keys are the languages (or `iv` for non-localized) fields and the values are the actual field values.
|
|||
///
|
|||
///You can use the `X-Flatten` header to return a flat structure when you query content items. This is more performant and easier for code generation. Unfortunantely it cannot be modelled with OpenAPI. Therefore we provide two different documents for your API.
|
|||
///
|
|||
///Read more about this [rest of string was truncated]";.
|
|||
/// </summary>
|
|||
internal static string OpenApiContentDescription { |
|||
get { |
|||
return ResourceManager.GetString("OpenApiContentDescription", resourceCulture); |
|||
} |
|||
} |
|||
|
|||
/// <summary>
|
|||
/// Looks up a localized string similar to The data of the content to be created or updated.
|
|||
///
|
|||
///Please note that each field is an object with one entry per language.
|
|||
///If the field is not localizable you must use `iv` (invariant language) as a key.
|
|||
///
|
|||
///Read more about it at: https://docs.squidex.io/04-guides/02-api.html.
|
|||
/// </summary>
|
|||
internal static string OpenApiSchemaBody { |
|||
get { |
|||
return ResourceManager.GetString("OpenApiSchemaBody", resourceCulture); |
|||
} |
|||
} |
|||
|
|||
/// <summary>
|
|||
/// Looks up a localized string similar to How to make queries?
|
|||
///
|
|||
///Read more about it at: https://docs.squidex.io/04-guides/02-api.html
|
|||
///
|
|||
///The query endpoints support three options:
|
|||
///
|
|||
///### Query with OData
|
|||
///
|
|||
///Squidex supports a subset of the OData (https://www.odata.org/) syntax with with the following query options:
|
|||
///
|
|||
///* **$top**: The $top query option requests the number of items in the queried collection to be included in the result. The default value is 20 and the maximum allowed value is 200. You can change the maximum in the app settings, when [rest of string was truncated]";.
|
|||
/// </summary>
|
|||
internal static string OpenApiSchemaQuery { |
|||
get { |
|||
return ResourceManager.GetString("OpenApiSchemaQuery", resourceCulture); |
|||
} |
|||
} |
|||
|
|||
/// <summary>
|
|||
/// Looks up a localized string similar to Squidex uses oauth2 client authentication. Read more about it at: https://oauth.net/2/ and https://tools.ietf.org/html/rfc6750.
|
|||
///
|
|||
///To retrieve an access token, the client id must make a request to the token url. For example:
|
|||
///
|
|||
/// $ curl
|
|||
/// -X POST '<TOKEN_URL>'
|
|||
/// -H 'Content-Type: application/x-www-form-urlencoded'
|
|||
/// -d 'grant_type=client_credentials&
|
|||
/// client_id=[CLIENT_ID]&
|
|||
/// client_secret=[CLIENT_SECRET]&
|
|||
/// scope=squidex-api'
|
|||
///
|
|||
///You must send this token in [rest of string was truncated]";.
|
|||
/// </summary>
|
|||
internal static string OpenApiSecurity { |
|||
get { |
|||
return ResourceManager.GetString("OpenApiSecurity", resourceCulture); |
|||
} |
|||
} |
|||
} |
|||
} |
|||
@ -0,0 +1,195 @@ |
|||
<?xml version="1.0" encoding="utf-8"?> |
|||
<root> |
|||
<!-- |
|||
Microsoft ResX Schema |
|||
|
|||
Version 2.0 |
|||
|
|||
The primary goals of this format is to allow a simple XML format |
|||
that is mostly human readable. The generation and parsing of the |
|||
various data types are done through the TypeConverter classes |
|||
associated with the data types. |
|||
|
|||
Example: |
|||
|
|||
... ado.net/XML headers & schema ... |
|||
<resheader name="resmimetype">text/microsoft-resx</resheader> |
|||
<resheader name="version">2.0</resheader> |
|||
<resheader name="reader">System.Resources.ResXResourceReader, System.Windows.Forms, ...</resheader> |
|||
<resheader name="writer">System.Resources.ResXResourceWriter, System.Windows.Forms, ...</resheader> |
|||
<data name="Name1"><value>this is my long string</value><comment>this is a comment</comment></data> |
|||
<data name="Color1" type="System.Drawing.Color, System.Drawing">Blue</data> |
|||
<data name="Bitmap1" mimetype="application/x-microsoft.net.object.binary.base64"> |
|||
<value>[base64 mime encoded serialized .NET Framework object]</value> |
|||
</data> |
|||
<data name="Icon1" type="System.Drawing.Icon, System.Drawing" mimetype="application/x-microsoft.net.object.bytearray.base64"> |
|||
<value>[base64 mime encoded string representing a byte array form of the .NET Framework object]</value> |
|||
<comment>This is a comment</comment> |
|||
</data> |
|||
|
|||
There are any number of "resheader" rows that contain simple |
|||
name/value pairs. |
|||
|
|||
Each data row contains a name, and value. The row also contains a |
|||
type or mimetype. Type corresponds to a .NET class that support |
|||
text/value conversion through the TypeConverter architecture. |
|||
Classes that don't support this are serialized and stored with the |
|||
mimetype set. |
|||
|
|||
The mimetype is used for serialized objects, and tells the |
|||
ResXResourceReader how to depersist the object. This is currently not |
|||
extensible. For a given mimetype the value must be set accordingly: |
|||
|
|||
Note - application/x-microsoft.net.object.binary.base64 is the format |
|||
that the ResXResourceWriter will generate, however the reader can |
|||
read any of the formats listed below. |
|||
|
|||
mimetype: application/x-microsoft.net.object.binary.base64 |
|||
value : The object must be serialized with |
|||
: System.Runtime.Serialization.Formatters.Binary.BinaryFormatter |
|||
: and then encoded with base64 encoding. |
|||
|
|||
mimetype: application/x-microsoft.net.object.soap.base64 |
|||
value : The object must be serialized with |
|||
: System.Runtime.Serialization.Formatters.Soap.SoapFormatter |
|||
: and then encoded with base64 encoding. |
|||
|
|||
mimetype: application/x-microsoft.net.object.bytearray.base64 |
|||
value : The object must be serialized into a byte array |
|||
: using a System.ComponentModel.TypeConverter |
|||
: and then encoded with base64 encoding. |
|||
--> |
|||
<xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"> |
|||
<xsd:import namespace="http://www.w3.org/XML/1998/namespace" /> |
|||
<xsd:element name="root" msdata:IsDataSet="true"> |
|||
<xsd:complexType> |
|||
<xsd:choice maxOccurs="unbounded"> |
|||
<xsd:element name="metadata"> |
|||
<xsd:complexType> |
|||
<xsd:sequence> |
|||
<xsd:element name="value" type="xsd:string" minOccurs="0" /> |
|||
</xsd:sequence> |
|||
<xsd:attribute name="name" use="required" type="xsd:string" /> |
|||
<xsd:attribute name="type" type="xsd:string" /> |
|||
<xsd:attribute name="mimetype" type="xsd:string" /> |
|||
<xsd:attribute ref="xml:space" /> |
|||
</xsd:complexType> |
|||
</xsd:element> |
|||
<xsd:element name="assembly"> |
|||
<xsd:complexType> |
|||
<xsd:attribute name="alias" type="xsd:string" /> |
|||
<xsd:attribute name="name" type="xsd:string" /> |
|||
</xsd:complexType> |
|||
</xsd:element> |
|||
<xsd:element name="data"> |
|||
<xsd:complexType> |
|||
<xsd:sequence> |
|||
<xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" /> |
|||
<xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" /> |
|||
</xsd:sequence> |
|||
<xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" /> |
|||
<xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" /> |
|||
<xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" /> |
|||
<xsd:attribute ref="xml:space" /> |
|||
</xsd:complexType> |
|||
</xsd:element> |
|||
<xsd:element name="resheader"> |
|||
<xsd:complexType> |
|||
<xsd:sequence> |
|||
<xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" /> |
|||
</xsd:sequence> |
|||
<xsd:attribute name="name" type="xsd:string" use="required" /> |
|||
</xsd:complexType> |
|||
</xsd:element> |
|||
</xsd:choice> |
|||
</xsd:complexType> |
|||
</xsd:element> |
|||
</xsd:schema> |
|||
<resheader name="resmimetype"> |
|||
<value>text/microsoft-resx</value> |
|||
</resheader> |
|||
<resheader name="version"> |
|||
<value>2.0</value> |
|||
</resheader> |
|||
<resheader name="reader"> |
|||
<value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value> |
|||
</resheader> |
|||
<resheader name="writer"> |
|||
<value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value> |
|||
</resheader> |
|||
<data name="OpenApiContentDescription" xml:space="preserve"> |
|||
<value># Introduction |
|||
|
|||
The API provides two specifications. The Content API usually returns one object per schema field where the keys are the languages (or `iv` for non-localized) fields and the values are the actual field values. |
|||
|
|||
You can use the `X-Flatten` header to return a flat structure when you query content items. This is more performant and easier for code generation. Unfortunantely it cannot be modelled with OpenAPI. Therefore we provide two different documents for your API. |
|||
|
|||
Read more about this here: https://docs.squidex.io/02-documentation/concepts/localization#how-to-use-the-api |
|||
|
|||
## Normal Content API |
|||
|
|||
All content fields are objects in the response. |
|||
|
|||
Go to: [REDOC_LINK_NORMAL] |
|||
|
|||
## Flat Content API |
|||
|
|||
All content fields are single values. |
|||
|
|||
Go to: [REDOC_LINK_SIMPLE]</value> |
|||
</data> |
|||
<data name="OpenApiSchemaBody" xml:space="preserve"> |
|||
<value>The data of the content to be created or updated. |
|||
|
|||
Please note that each field is an object with one entry per language. |
|||
If the field is not localizable you must use `iv` (invariant language) as a key. |
|||
|
|||
Read more about it at: https://docs.squidex.io/04-guides/02-api.html</value> |
|||
</data> |
|||
<data name="OpenApiSchemaQuery" xml:space="preserve"> |
|||
<value>How to make queries? |
|||
|
|||
Read more about it at: https://docs.squidex.io/04-guides/02-api.html |
|||
|
|||
The query endpoints support three options: |
|||
|
|||
### Query with OData |
|||
|
|||
Squidex supports a subset of the OData (https://www.odata.org/) syntax with with the following query options: |
|||
|
|||
* **$top**: The $top query option requests the number of items in the queried collection to be included in the result. The default value is 20 and the maximum allowed value is 200. You can change the maximum in the app settings, when you host Squidex yourself. |
|||
* **$skip**: The $skip query option requests the number of items in the queried collection that are to be skipped and not included in the result. Use it together with $top to read the all your data page by page. |
|||
* **$search**: The $search query option allows clients to request entities matching a free-text search expression. We add the data of all fields for all languages to our full text engine. |
|||
* **$filter**: The $filter query option allows clients to filter a collection of resources that are addressed by a request URL. |
|||
* **$orderby**: The $orderby query option allows clients to request resources in a particular order. |
|||
|
|||
### Query with JSON query |
|||
|
|||
Squidex also supports a query syntax based on JSON. You have to pass in the query object as query parameter: |
|||
|
|||
* **q**: A json text that represents the same query options as with OData, but is more performant to parse. |
|||
|
|||
### Query by IDs |
|||
|
|||
Query your items by passing in one or many IDs with the following query parameter: |
|||
|
|||
* **ids**: A comma-separated list of ids. If you define this option all other settings are ignored.</value> |
|||
</data> |
|||
<data name="OpenApiSecurity" xml:space="preserve"> |
|||
<value>Squidex uses oauth2 client authentication. Read more about it at: https://oauth.net/2/ and https://tools.ietf.org/html/rfc6750. |
|||
|
|||
To retrieve an access token, the client id must make a request to the token url. For example: |
|||
|
|||
$ curl |
|||
-X POST '<TOKEN_URL>' |
|||
-H 'Content-Type: application/x-www-form-urlencoded' |
|||
-d 'grant_type=client_credentials& |
|||
client_id=[CLIENT_ID]& |
|||
client_secret=[CLIENT_SECRET]& |
|||
scope=squidex-api' |
|||
|
|||
You must send this token in the `Authorization` header when making requests to the API: |
|||
|
|||
Authorization: Bearer <token></value> |
|||
</data> |
|||
</root> |
|||
Loading…
Reference in new issue