Update README and add Getting Started Tutorial, Swift Package Plugin docs, CONTRIBUTING guidance + more by liamnichols · Pull Request #82 · CreateAPI/CreateAPI

liamnichols · Aug 3, 2022

Background

closes Any docs on how to actually use the generated code? #58
closes Support Swift Package Plugins #48

In the past, we never invested much time documenting the tool and best practices around using it. To help with adoption of all the awesome features in CreateAPI, we want to make sure that people now how to use them and the aim here is to do that via plenty of documentation.

Changes

To get an overall feel for the changes, check out the repo here: https://github.com/CreateAPI/CreateAPI/tree/ln/documentation

In particular, I've done the following:

Rewritten README.md
Added CONTRIBUTING.md
Written a tutorial: Generating an API with CreateAPI
Documented Swift Package Plugins
Added some notes about Dependencies
Kick started an Advanced Setup doc with a guide to "Using a different API Client"

Some of the contents in this PR rely on tweaks that are still upcoming for the 0.1 release, so it might not quite match to how CreateAPI is used today.. I'll add notes inline.

liamnichols · Aug 3, 2022

CONTRIBUTING.md

+
+If you want to add a new spec or configuration to the tests, you can add the schema to **Tests/CreateAPITests/Specs/** and then write a new test, with the desired configuration in **GenerateTests.swift**. Be sure to enable `generateSnapshots` on the first run.
+
+In addition if you've generated a package, you should include it in **Tests/CreateAPITests/AllPackages/Package.swift** so that CI checks can confirm that it compiles ok on both macOS and Linux.


Only accurate after #81

Docs/AdvancedSetup.md

Docs/Dependencies.md

liamnichols · Aug 3, 2022

Docs/OpenAPISupport.md

+# OpenAPI Support
+
+The goal is to completely cover OpenAPI 3.x spec.
+
+Currently, the following features are **not** supported:
+
+- External References
+
+Some discrepancies with the OpenAPI spec are by design:
+
+- `allowReserved` keyword in parameters is ignored and all parameter values are percent-encoded
+- `allowEmptyValue` keyword in parameters is ignored as it's not recommended to be used


This was in the README.md, I moved it here but didn't change it's contents (other than removing "upcoming")

Docs/Tutorial.md

README.md

liamnichols · Aug 3, 2022

cc @soemarko, @rusik, @mgrider, @LePips, @kean... Any feedback on this will be much appreciated, thanks!

mgrider · Aug 3, 2022

Docs/Tutorial.md

+
+Now that you have the generated Paths and Entities, you probably want to actually put them to good use!
+
+In the **Sources** directory, add a new file called **PetstoreClient.swift**. Within that file, add the following code:


I kind of think you should add a note here about how you don't have to modify the generated package, you can instead include it in your own project. For APIs that are in development simultaneously to the Swift project, you'll probably be generating the package over and over again during development, so modifying it directly is probably not a great idea.

This leads me to my next thought, which is maybe there could be a "best practices" document with some tips and tricks in it? A couple of ideas for that:

Put your CreateAPI generation command in a bash script that's checked into git somewhere, (along side the generated package), so it's easy for anyone on the project to update the API by running the script.

A note about writing tests that check for all the properties in the generated package that you are using specifically, so when the API is updated you can run your tests and make sure the API still gives you back the objects and properties you are using in your application.

I see that you do address overwriting changes to the generated package when talking about modules. I still think a note about using the package as opposed to modifying it here would be nice.

Since package is the default/recommended option (AFIAR), ideally you should never modify its contents. One of the main initial goals was to provide enough tools to generate code that compiles and you are happy with, making this workflow (always autogenerate) feasible.

There is also a --watch option (for autogeneration) which I'm not sure is documented.

So the aim of from the tutorial was to demonstrate both approaches to help you understand what is possible. It wasn't necessarily to say "you must do it like this" but I guess that I can make that a bit clearer 👍

I still think a note about using the package as opposed to modifying it here would be nice.

I'll do this then 👍

Since package is the default/recommended option (AFIAR), ideally you should never modify its contents. One of the main initial goals was to provide enough tools to generate code that compiles and you are happy with, making this workflow (always autogenerate) feasible.

Yup that's cool.

From trying things out, I guess the current issue I found with how CreateAPI works today is that you can't add extra targets or tests. The idea of having CreateAPI generate the whole package is great, but it means that the rest of your project has to go in a separate project/package where traditionally you might have just had them as two targets in the same package.

For example, I personally use CreateAPI today in --module mode to integrate it into my existing networking client which has to do a lot of other stuff (mostly related to auth). appstoreconnect-swift-sdk also does something very similar.

I'll add a note, but I agree that it would be great to revisit this in the future once we've built on the current capabilities somewhat.

For example, I had an shower thought that maybe we could benefit from a create-api init command that offers a guided process to setup a package (repo), pull the schema into the right location, set a default config and even integrate a Swift Package Plugin to enable easy regeneration each time its required 😬

I was thinking about a scenario where you have an Xcode Project, you generate the package in one of the subfolders, and then integrate it as a local dependency.

To be honest, it does sound like a perfect use case too so I think it's a great idea supporting both. The majority of my SPM experience comes from outside of macOS/iOS Xcode Projects so I haven't thought much about this before.

I plan to add the above disclaimer to the document:

Suggested change

In the **Sources** directory, add a new file called **PetstoreClient.swift**. Within that file, add the following code:

> **Note**: In some cases, you might prefer to use the generated Package as-is by referencing it as a dependency in another project or package (this allows you to regenerate it whenever the spec changes), but for the educational purposes in this tutorial you will work directly inside the package instead.

In the **Sources** directory, add a new file called **PetstoreClient.swift**. Within that file, add the following code:

I was thinking about a scenario where you have an Xcode Project, you generate the package in one of the subfolders, and then integrate it as a local dependency.

This is definitely how I'm using it currently. Personally, I love that it's a separate package and import.

Good to know thank you. I think there certainly is still room for another document that lists out various different possibilities explaining how you can go about using CreateAPI. It'll even be useful for me/other maintainers 😄

I'll probably leave it out of this PR for now, but might come back to it after if somebody else doesn't beat me to it.

So I've actually revisited this when updating everything to reflect the changes in 0.1.0. I decided to focus the tutorial entirely on generating packages and make no mention of the alternative approach.

Later on I will add to the AdvancedSetup.md with instructions on how to integrate into an existing project 👍

I went and took a look at your new Tutorial, and it's fantastic! Really excellent work! 🤩

mgrider

I had some suggestions, but overall I really love the improvements here. A+ work!

kean

Impressive work on the docs!

Docs/AdvancedSetup.md

kean · Aug 3, 2022

Docs/README.md

+
+Here you can find documentation specific for using CreateAPI.
+
+- [Tutorial: Generating an API with CreateAPI](./Tutorial.md)


Have you considered generating the documentation using DocC?

It crossed my mind, but I haven't looked into it too much. Something totally worth doing in the future though once we've build up and stabilised the docs I think 👍

Docs/Tutorial.md

kean · Aug 3, 2022

Docs/Tutorial.md

+
+Now that you have the generated Paths and Entities, you probably want to actually put them to good use!
+
+In the **Sources** directory, add a new file called **PetstoreClient.swift**. Within that file, add the following code:


Since package is the default/recommended option (AFIAR), ideally you should never modify its contents. One of the main initial goals was to provide enough tools to generate code that compiles and you are happy with, making this workflow (always autogenerate) feasible.

kean · Aug 3, 2022

Docs/Tutorial.md

+
+Now that you have the generated Paths and Entities, you probably want to actually put them to good use!
+
+In the **Sources** directory, add a new file called **PetstoreClient.swift**. Within that file, add the following code:


There is also a --watch option (for autogeneration) which I'm not sure is documented.

CONTRIBUTING.md

LePips · Aug 3, 2022

Looks great!

README.md

liamnichols force-pushed the ln/documentation branch from eafc510 to 1a868e8 Compare August 3, 2022 14:21

liamnichols self-assigned this Aug 3, 2022

liamnichols added this to the 0.1.0 milestone Aug 3, 2022

liamnichols commented Aug 3, 2022

View reviewed changes

liamnichols marked this pull request as ready for review August 3, 2022 14:34

mgrider reviewed Aug 3, 2022

View reviewed changes

mgrider approved these changes Aug 3, 2022

View reviewed changes

kean reviewed Aug 3, 2022

View reviewed changes

LePips reviewed Aug 3, 2022

View reviewed changes

CONTRIBUTING.md Outdated Show resolved Hide resolved

liamnichols mentioned this pull request Aug 4, 2022

Add official way to opt out of using Get #84

Open

liamnichols force-pushed the ln/documentation branch from 8aebfc0 to 0327183 Compare August 4, 2022 12:50

LePips suggested changes Aug 4, 2022

View reviewed changes

README.md Show resolved Hide resolved

LePips approved these changes Aug 4, 2022

View reviewed changes

LePips mentioned this pull request Aug 4, 2022

Remove option isSwiftLintDisabled? #94

Closed

liamnichols mentioned this pull request Aug 4, 2022

📝 0.1.0 Release #101

Closed

27 tasks

liamnichols added 13 commits August 13, 2022 18:10

Write 'Generating an API with CreateAPI' tutorial

3926fab

Add a technical note about dependencies

ee7177d

Add a technical note about OpenAPI support

23b7db4

Add AdvancedSetup documentation

7d83427

Add documentation for Swift Package Plugins

b01a008

Add CONTRIBUTING.md

84014c4

Update README.md

c47a62c

Move Releasing notes to CONTRINUTING.md

a3b839e

Add disclaimer about not editing generated package

e83572e

Update Dependencies.md to reference Get as 1.0.2 or later

4c5c411

Update documentation to demonstrate using --split

1cfe4bd

Update Help text in README.md

6a2a79a

Add better README introduction based on 0.1 behaviour

06a20b6

liamnichols added 5 commits August 13, 2022 18:33

Update CONTRIBUTING.md to reflect changes to how we rcord snapshots

ed29ab0

Update SwiftPackagePlugins to use 0.1 style arguments

bfa6061

Update Dependencies.md to use renamed option names

1f06415

Rewrite the tutorial to focus entirely on Package generation

fa344f9

Update the version number to 0.1.0

9d21768

liamnichols force-pushed the ln/documentation branch from 0327183 to 9d21768 Compare August 13, 2022 17:50

liamnichols merged commit ea1b9d7 into main Aug 14, 2022

liamnichols deleted the ln/documentation branch August 14, 2022 20:26


		If you want to add a new spec or configuration to the tests, you can add the schema to Tests/CreateAPITests/Specs/ and then write a new test, with the desired configuration in GenerateTests.swift. Be sure to enable `generateSnapshots` on the first run.

		In addition if you've generated a package, you should include it in Tests/CreateAPITests/AllPackages/Package.swift so that CI checks can confirm that it compiles ok on both macOS and Linux.


		Now that you have the generated Paths and Entities, you probably want to actually put them to good use!

		In the Sources directory, add a new file called PetstoreClient.swift. Within that file, add the following code:


		Here you can find documentation specific for using CreateAPI.

		- [Tutorial: Generating an API with CreateAPI](./Tutorial.md)

Search code, repositories, users, issues, pull requests...

Comments

Conversation

liamnichols commented Aug 3, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

Changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

liamnichols commented Aug 3, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mgrider left a comment

Choose a reason for hiding this comment

Uh oh!

kean left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

LePips commented Aug 3, 2022

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

liamnichols commented Aug 3, 2022 •

edited

Loading