Merge pull request #1386 from nextcloud/test/dynamite/document-output

fix(dynamite): test documentation of generated libraries

cspell.json

@@ -12,6 +12,7 @@
     "**/assets",
     "**/l10n/!(en.arb)",
     "**.openapi.dart",
+    "**.openapi.json",
     "external",
     "packages/dynamite/dynamite/example/lib",
     "packages/file_icons/lib/src/data.dart",

packages/dynamite/dynamite/example/lib/petstore.openapi.dart

@@ -1,10 +1,25 @@
+// Use of this source code is governed by a Apache 2.0 license. It can be obtained at `https://www.apache.org/licenses/LICENSE-2.0.html`.
+
 // OpenAPI client generated by Dynamite. Do not manually edit this file.
 
 // ignore_for_file: camel_case_types, discarded_futures
 // ignore_for_file: no_leading_underscores_for_local_identifiers
 // ignore_for_file: public_member_api_docs, unreachable_switch_case
 
-// ignore_for_file: no_leading_underscores_for_library_prefixes
+/// Swagger Petstore Version: 1.0.0.
+///
+/// A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification.
+///
+/// You can contact the Swagger API Team team under:
+///   Email: `[email protected]`.
+///   Website: `http://swagger.io`.
+///
+/// Use of this source code is governed by a Apache 2.0 license.
+/// It can be obtained at `https://www.apache.org/licenses/LICENSE-2.0.html`.
+///
+/// Usage of these apis must adhere to the terms of service: `http://swagger.io/terms/`.
+library; // ignore_for_file: no_leading_underscores_for_library_prefixes
+
 import 'dart:convert';
 import 'dart:typed_data';
 

packages/dynamite/dynamite/lib/src/builder/generate_schemas.dart

@@ -21,11 +21,15 @@ Iterable<Spec> generateSchemas(
 
       // TypeDefs should only be generated for top level schemas.
       if (result is TypeResultBase || result.isTypeDef) {
-        yield TypeDef(
-          (b) => b
+        yield TypeDef((b) {
+          if (!(state.buildConfig.analyzerIgnores?.contains('public_member_api_docs') ?? false)) {
+            b.docs.add('// ignore: public_member_api_docs');
+          }
+
+          b
             ..name = identifier
-            ..definition = refer(result.dartType.name),
-        );
+            ..definition = refer(result.dartType.name);
+        });
       }
     }
   }

packages/dynamite/dynamite/lib/src/builder/resolve_interface.dart

@@ -40,11 +40,16 @@ Spec buildInterface(
   String identifier, {
   BuiltList<Method>? methods,
   Iterable<TypeResultObject>? interfaces,
+  Iterable<String>? documentation,
 }) {
   assert((interfaces == null) != (methods == null), 'Either provide an interface or methods.');
   final className = '\$$identifier$interfaceSuffix';
 
   return Class((b) {
+    if (documentation != null) {
+      b.docs.addAll(documentation);
+    }
+
     b
       ..abstract = true
       ..modifier = ClassModifier.interface

packages/dynamite/dynamite/lib/src/builder/resolve_object.dart

@@ -89,6 +89,7 @@ TypeResultObject resolveObject(
     final $interface = buildInterface(
       identifier,
       methods: methods.build(),
+      documentation: schema.formattedDescription,
     );
     final $class = buildBuiltClass(
       identifier,

packages/dynamite/dynamite/lib/src/builder/resolve_ofs.dart

@@ -130,6 +130,7 @@ TypeResult resolveAllOf(
       identifier,
       interfaces: interfaces,
       methods: methods.build(),
+      documentation: schema.formattedDescription,
     );
 
     final $class = buildBuiltClass(

packages/dynamite/dynamite/lib/src/helpers/docs.dart

@@ -5,7 +5,7 @@ Iterable<String> descriptionToDocs(String? description) sync* {
     for (final line in description.split('\n')) {
       final buffer = StringBuffer('$docsSeparator ')..write(line);
 
-      if (!line.endsWith('.') && line.isNotEmpty) {
+      if (!line.endsWith('.') && !line.endsWith(':') && line.isNotEmpty) {
         buffer.write('.');
       }
 

packages/dynamite/dynamite/lib/src/models/openapi.dart

@@ -3,6 +3,7 @@ import 'package:built_value/json_object.dart';
 import 'package:built_value/serializer.dart';
 import 'package:built_value/standard_json_plugin.dart';
 import 'package:dynamite/src/models/openapi/components.dart';
+import 'package:dynamite/src/models/openapi/contact.dart';
 import 'package:dynamite/src/models/openapi/discriminator.dart';
 import 'package:dynamite/src/models/openapi/header.dart';
 import 'package:dynamite/src/models/openapi/info.dart';
@@ -42,6 +43,7 @@ part 'openapi.g.dart';
 
 @SerializersFor([
   Components,
+  Contact,
   Discriminator,
   Header,
   Info,

packages/dynamite/dynamite/lib/src/models/openapi/contact.dart

@@ -0,0 +1,40 @@
+import 'package:built_value/built_value.dart';
+import 'package:built_value/serializer.dart';
+
+part 'contact.g.dart';
+
+abstract class Contact implements Built<Contact, ContactBuilder> {
+  factory Contact([void Function(ContactBuilder) updates]) = _$Contact;
+
+  const Contact._();
+
+  static Serializer<Contact> get serializer => _$contactSerializer;
+
+  String? get name;
+  String? get url;
+  String? get email;
+
+  String? formattedDescription() {
+    final name = this.name;
+    final url = this.url;
+    final email = this.email;
+
+    if (name == null || (url ?? email) == null) {
+      return null;
+    }
+
+    final buffer = StringBuffer('You can contact the $name team under:');
+    if (email != null) {
+      buffer
+        ..write('\n')
+        ..write('  Email: `$email`');
+    }
+    if (url != null) {
+      buffer
+        ..write('\n')
+        ..write('  Website: `$url`');
+    }
+
+    return buffer.toString();
+  }
+}

packages/dynamite/dynamite/lib/src/models/openapi/info.dart

@@ -1,5 +1,7 @@
 import 'package:built_value/built_value.dart';
 import 'package:built_value/serializer.dart';
+import 'package:dynamite/src/helpers/docs.dart';
+import 'package:dynamite/src/models/openapi/contact.dart';
 import 'package:dynamite/src/models/openapi/license.dart';
 
 part 'info.g.dart';
@@ -18,6 +20,53 @@ abstract class Info implements Built<Info, InfoBuilder> {
 
   License? get license;
 
+  Contact? get contact;
+
   @BuiltValueField(compare: false)
   String? get description;
+
+  String? get termsOfService;
+
+  String? get summary;
+
+  Iterable<String> formattedDescription() {
+    final buffer = StringBuffer()..write('$title Version: $version');
+
+    final summary = this.summary;
+    if (summary != null && summary.isNotEmpty) {
+      buffer
+        ..write('\n')
+        ..write(summary);
+    }
+
+    final description = this.description;
+    if (description != null && description.isNotEmpty) {
+      buffer
+        ..write('\n\n')
+        ..write(description);
+    }
+
+    final contact = this.contact;
+    if (contact != null) {
+      buffer
+        ..write('\n\n')
+        ..write(contact.formattedDescription());
+    }
+
+    final license = this.license;
+    if (license != null) {
+      buffer
+        ..write('\n\n')
+        ..write(license.formattedDescription(singleLine: false));
+    }
+
+    final termsOfService = this.termsOfService;
+    if (termsOfService != null) {
+      buffer
+        ..write('\n\n')
+        ..write('Usage of these apis must adhere to the terms of service: `$termsOfService`');
+    }
+
+    return descriptionToDocs(buffer.toString());
+  }
 }