Repository: pydantic/pydantic

Issue:
More things to document
I've been doing some in depth stuff with pydantic and discovered we don't have great documentation for:
* `WithJsonSchema` - needs to be talked about on the JSON Schema page, with an example, link to docs
* `__get_pydantic_json_schema__` - on same page, needs an example


Discussion:
Will do today. Also going to add better docs / examples for `SkipJsonSchema`
Unless I'm mistaken, I haven't found any reference to `computed_field` in concepts (apart from a note in [Serialization](https://docs.pydantic.dev/latest/concepts/serialization/)). It might be beneficial to have a dedicated section? What do you think?
@Viicos,

Good call - probably makes sense to have a section in the `Fields` concepts section. I can add that as well 😄
Also `json_schema_extra` with a callable 😄

Resolving patch:
diff --git a/pydantic/fields.py b/pydantic/fields.py
--- a/pydantic/fields.py
+++ b/pydantic/fields.py
@@ -96,7 +96,7 @@ class FieldInfo(_repr.Representation):
         examples: List of examples of the field.
         exclude: Whether to exclude the field from the model serialization.
         discriminator: Field name or Discriminator for discriminating the type in a tagged union.
-        json_schema_extra: Dictionary of extra JSON schema properties.
+        json_schema_extra: A dict or callable to provide extra JSON schema properties.
         frozen: Whether the field is frozen.
         validate_default: Whether to validate the default value of the field.
         repr: Whether to include the field in representation of the model.
@@ -719,7 +719,7 @@ def Field(  # noqa: C901
         examples: Example values for this field.
         exclude: Whether to exclude the field from the model serialization.
         discriminator: Field name or Discriminator for discriminating the type in a tagged union.
-        json_schema_extra: Any additional JSON schema data for the schema property.
+        json_schema_extra: A dict or callable to provide extra JSON schema properties.
         frozen: Whether the field is frozen.
         validate_default: Run validation that isn't only checking existence of defaults. This can be set to `True` or `False`. If not set, it defaults to `None`.
         repr: A boolean indicating whether to include the field in the `__repr__` output.
@@ -954,7 +954,7 @@ class ComputedFieldInfo:
         title: Title of the computed field as in OpenAPI document, should be a short summary.
         description: Description of the computed field as in OpenAPI document.
         examples: Example values of the computed field as in OpenAPI document.
-        json_schema_extra: Dictionary of extra JSON schema properties.
+        json_schema_extra: A dict or callable to provide extra JSON schema properties.
         repr: A boolean indicating whether or not to include the field in the __repr__ output.
     """
 
@@ -1019,7 +1019,9 @@ def computed_field(
     repr: bool | None = None,
     return_type: Any = PydanticUndefined,
 ) -> PropertyT | typing.Callable[[PropertyT], PropertyT]:
-    """Decorator to include `property` and `cached_property` when serializing models or dataclasses.
+    """Usage docs: https://docs.pydantic.dev/2.6/concepts/fields#the-computed_field-decorator
+
+    Decorator to include `property` and `cached_property` when serializing models or dataclasses.
 
     This is useful for fields that are computed from other fields, or for fields that are expensive to compute and should be cached.
 
@@ -1143,7 +1145,7 @@ def _private_property(self) -> int:
         description: Description to use when including this computed field in JSON Schema, defaults to the function's
             docstring
         examples: Example values to use when including this computed field in JSON Schema
-        json_schema_extra: Dictionary of extra JSON schema properties.
+        json_schema_extra: A dict or callable to provide extra JSON schema properties.
         repr: whether to include this computed field in model repr.
             Default is `False` for private properties and `True` for public properties.
         return_type: optional return for serialization logic to expect when serializing to JSON, if included
diff --git a/pydantic/json_schema.py b/pydantic/json_schema.py
--- a/pydantic/json_schema.py
+++ b/pydantic/json_schema.py
@@ -2243,7 +2243,9 @@ def _sort_json_schema(value: JsonSchemaValue, parent_key: str | None = None) ->
 
 @dataclasses.dataclass(**_internal_dataclass.slots_true)
 class WithJsonSchema:
-    """Add this as an annotation on a field to override the (base) JSON schema that would be generated for that field.
+    """Usage docs: https://docs.pydantic.dev/2.6/concepts/json_schema/#withjsonschema-annotation
+
+    Add this as an annotation on a field to override the (base) JSON schema that would be generated for that field.
     This provides a way to set a JSON schema for types that would otherwise raise errors when producing a JSON schema,
     such as Callable, or types that have an is-instance core schema, without needing to go so far as creating a
     custom subclass of pydantic.json_schema.GenerateJsonSchema.
@@ -2330,20 +2332,53 @@ def _get_all_json_refs(item: Any) -> set[JsonRef]:
 
     @dataclasses.dataclass(**_internal_dataclass.slots_true)
     class SkipJsonSchema:
-        """Add this as an annotation on a field to skip generating a JSON schema for that field.
+        """Usage docs: https://docs.pydantic.dev/2.6/concepts/json_schema/#skipjsonschema-annotation
+
+        Add this as an annotation on a field to skip generating a JSON schema for that field.
 
         Example:
             ```py
+            from typing import Union
+
             from pydantic import BaseModel
             from pydantic.json_schema import SkipJsonSchema
 
-            class Model(BaseModel):
-                a: int | SkipJsonSchema[None] = None
+            from pprint import pprint
 
 
-            print(Model.model_json_schema())
-            #> {'properties': {'a': {'default': None, 'title': 'A', 'type': 'integer'}}, 'title': 'Model', 'type': 'object'}
+            class Model(BaseModel):
+                a: Union[int, None] = None  # (1)!
+                b: Union[int, SkipJsonSchema[None]] = None  # (2)!
+                c: SkipJsonSchema[Union[int, None]] = None  # (3)!
+
+
+            pprint(Model.model_json_schema())
+            '''
+            {
+                'properties': {
+                    'a': {
+                        'anyOf': [
+                            {'type': 'integer'},
+                            {'type': 'null'}
+                        ],
+                        'default': None,
+                        'title': 'A'
+                    },
+                    'b': {
+                        'default': None,
+                        'title': 'B',
+                        'type': 'integer'
+                    }
+                },
+                'title': 'Model',
+                'type': 'object'
+            }
+            '''
             ```
+
+            1. The integer and null types are both included in the schema for `a`.
+            2. The integer type is the only type included in the schema for `b`.
+            3. The entirety of the `c` field is omitted from the schema.
         """
 
         def __class_getitem__(cls, item: AnyType) -> AnyType:


Test patch: